{"id":49305328,"url":"https://github.com/fraction12/microcanvas","last_synced_at":"2026-04-26T09:04:29.734Z","repository":{"id":352795797,"uuid":"1216642392","full_name":"fraction12/microcanvas","owner":"fraction12","description":"A lightweight, reliable canvas tool for AI coding tools.","archived":false,"fork":false,"pushed_at":"2026-04-21T07:12:29.000Z","size":38650,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T07:36:19.063Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fraction12.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-21T05:19:27.000Z","updated_at":"2026-04-21T07:12:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fraction12/microcanvas","commit_stats":null,"previous_names":["fraction12/microcanvas"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/fraction12/microcanvas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fmicrocanvas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fmicrocanvas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fmicrocanvas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fmicrocanvas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fraction12","download_url":"https://codeload.github.com/fraction12/microcanvas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraction12%2Fmicrocanvas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32291347,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T08:29:33.829Z","status":"ssl_error","status_checked_at":"2026-04-26T08:29:18.366Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-26T09:04:08.442Z","updated_at":"2026-04-26T09:04:29.725Z","avatar_url":"https://github.com/fraction12.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Microcanvas banner](https://raw.githubusercontent.com/fraction12/microcanvas/main/docs/assets/readme-banner.png)\n\n# microcanvas\n\n![stage: early](https://img.shields.io/badge/stage-early-orange)\n![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)\n![platform: macOS-first](https://img.shields.io/badge/platform-macOS--first-blue)\n![focus: AI tooling](https://img.shields.io/badge/focus-AI%20tooling-teal)\n\nMicrocanvas is a tiny stagehand for AI tools: it renders supported files, opens them in a viewer, keeps track of the active surface, and helps agents verify what they are showing.\n\nIt is usable today, still early-stage, and very happy to hold the curtain open while your tool says, \"Would you like me to show it on Microcanvas?\"\n\n## Why Microcanvas Exists\n\nMost coding agents eventually need the same thing: a predictable place to render a file, open it, update it, inspect runtime state, and grab evidence that the right thing is on screen.\n\nMicrocanvas exists to do that job cleanly.\n\n- Render a source file into a surface\n- Show the active surface in a native viewer when available\n- Update the active surface without losing identity\n- Report runtime and viewer state in a tool-friendly way\n- Verify or snapshot the active surface when native viewer capability is present\n\nThis repo is intentionally focused. It is not trying to be a full document suite, a browser automation framework, or a giant cross-platform GUI toolkit.\n\n## What The Claws Can Do Today\n\n- `render` stages a supported source into a Microcanvas surface\n- `show` activates a surface and opens it, preferring the native Microcanvas viewer\n- `update` refreshes the active surface while keeping surface identity intact\n- `status` reports runtime state, active artifact, lock state, and viewer capability\n- `verify` checks active files plus native-viewer-backed confirmation for the active surface\n- `snapshot` captures a real PNG from the native viewer when snapshot capability is available\n\n## Take It For A Spin\n\nMicrocanvas accepts supported local source files from anywhere on disk, then ingests them into Microcanvas-owned runtime paths before presentation. Clone it, build it locally, and run the CLI from source:\n\n```bash\nnpm install\nnpm run build\nnode dist/cli/index.js show README.md\nnode dist/cli/index.js status --json\n```\n\nThat gives you the happy-path tour:\n\n- `npm install` pulls the local repo dependencies\n- `npm run build` compiles the CLI into `dist/`\n- `show README.md` opens this README as the active surface\n- `status --json` reports the runtime and viewer state in a tool-friendly format\n\nOnce a surface is active, the next useful moves are:\n\n```bash\nnode dist/cli/index.js update README.md\nnode dist/cli/index.js verify --json\nnode dist/cli/index.js snapshot --json\n```\n\n## Quick Command Tour\n\n### Show Something Off\n\n```bash\nmicrocanvas show path/to/file.md\nmicrocanvas show /tmp/exported-note.md\nmicrocanvas show path/to/file.png\nmicrocanvas show path/to/file.csv --json\nmicrocanvas show path/to/diagram.mmd\n```\n\nUse `show` when you want Microcanvas to render if needed, activate the result, and open it.\n\n### Stage Without Opening\n\n```bash\nmicrocanvas render path/to/file.md --json\n```\n\nUse `render` when you want a staged surface artifact without activating it yet.\n\n### Refresh The Active Surface\n\n```bash\nmicrocanvas update path/to/file.md --json\n```\n\nUse `update` when a surface is already active and you want to refresh it in place.\n\n### Ask What Is Going On\n\n```bash\nmicrocanvas status --json\nmicrocanvas verify --json\n```\n\nUse `status` for inspection. Use `verify` when you need strict confirmation that the active surface and viewer state line up.\n\n### Grab A Snapshot\n\n```bash\nmicrocanvas snapshot --json\n```\n\nWhen native snapshot capability is available, Microcanvas writes a real PNG snapshot and reports its path in the command result.\n\n## Supported Content\n\nMicrocanvas is deliberately honest about what it can display today.\n\nSupported now:\n\n- `.html`, `.htm` rendered as real local browser-style surfaces with JS/CSS/layout preserved\n- `.md`, `.markdown` rendered to sanitized HTML\n- `.mmd`, `.mermaid` rendered into Mermaid diagram surfaces automatically\n- `.pdf`\n- `.csv` rendered into a deterministic HTML table surface\n- `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`\n- `.txt`, `.json`, `.js`, `.ts` wrapped into a sanitized HTML code-view surface\n\nNot supported yet:\n\n- arbitrary binary artifacts\n- archives like `.zip`\n- `.svg` and other image-like formats without an explicit display path\n- office docs and other formats without an explicit render/display path\n\nIf a file type is not supported, Microcanvas returns `UNSUPPORTED_CONTENT` instead of pretending everything is fine.\n\n## Viewer Modes\n\nMicrocanvas separates \"something opened\" from \"the native viewer is fully available.\"\n\n- `native`: the Microcanvas viewer heartbeat is fresh and can satisfy `verify` and `snapshot`\n- `degraded`: the active artifact opened through an external fallback path, but native verification and snapshot flows are unavailable\n- `closed`: there is no confirmed viewer session\n\nThis matters in practice:\n\n- `show` and `update` prefer the packaged `MicrocanvasViewer.app` on macOS, then fall back to development launch paths when needed\n- `show` and `update` only report `native` after the viewer heartbeat confirms readiness, and the native app brings its window to the front when new content is presented when macOS allows it\n- `show --native` and `update --native` require native verification and return `VIEWER_LAUNCH_FAILED` instead of using degraded fallback\n- raw `.html` and `.htm` surfaces are presented as real local browser-style content by default, with JavaScript enabled and local asset access scoped to the ingested surface copy\n- Markdown/code/table/Mermaid surfaces still render through Microcanvas-owned HTML presentation output\n- if an older native viewer session is still hanging around, Microcanvas clears that stale session before trusting a new launch attempt\n- `show` and `update` can still succeed in degraded mode\n- `status` tells you what kind of runtime/viewer state you currently have\n- `verify` stays strict and requires native viewer-backed confirmation\n- `snapshot` is strongest when native capture capability is available\n\n## JSON Contract\n\nMicrocanvas treats AgentTK as the canonical CLI/result layer.\n\nSuccess responses return:\n\n- `ok: true`\n- `record`: Microcanvas runtime data such as `surfaceId`, artifact paths, lock state, and viewer mode\n- `warnings`: optional warnings, especially for degraded-mode success\n- `verificationStatus`: whether the result is verified, unverified, or not applicable\n- `nextAction`: optional follow-up guidance when the result is useful but not fully verifiable\n\nFailure responses return:\n\n- `ok: false`\n- `error.code`: stable domain codes such as `INVALID_INPUT`, `UNSUPPORTED_CONTENT`, `LOCKED_TRY_LATER`, `SURFACE_NOT_FOUND`, `UPDATE_NOT_SUPPORTED`, `VIEWER_LAUNCH_FAILED`, or `VERIFY_FAILED`\n- `error.message`: human-readable failure detail\n\nExample degraded `show` response:\n\n```json\n{\n  \"ok\": true,\n  \"record\": {\n    \"surfaceId\": \"surface-123\",\n    \"artifacts\": {\n      \"primary\": \"/path/to/runtime/active/index.html\"\n    },\n    \"viewer\": {\n      \"mode\": \"degraded\",\n      \"open\": true,\n      \"canVerify\": false\n    },\n    \"lock\": {\n      \"held\": false\n    }\n  },\n  \"warnings\": [\n    \"Native viewer is unavailable; opened the active artifact through the degraded external display path.\"\n  ],\n  \"verificationStatus\": \"unverified\",\n  \"nextAction\": \"verify_state\"\n}\n```\n\nExample degraded `verify` failure:\n\n```json\n{\n  \"ok\": false,\n  \"error\": {\n    \"code\": \"VERIFY_FAILED\",\n    \"message\": \"Native viewer confirmation is unavailable while the runtime is in degraded display mode\"\n  }\n}\n```\n\n## Runtime Shape\n\nMicrocanvas keeps a canonical runtime root with:\n\n- `runtime/active/`\n- `runtime/staging/`\n- `runtime/snapshots/`\n- `runtime/state.json`\n- `runtime/viewer-state.json`\n- request/response files used for viewer snapshot handoff\n\nEach surface is ingested through a source-versus-presentation boundary:\n\n- the caller can point at a supported local file from inside or outside the repo\n- Microcanvas copies that source into a surface-owned `source/` directory under staging/active\n- the viewer presents only the staged artifact under `runtime/staging` or `runtime/active`\n- the original source path is recorded in manifest/result metadata for operator and tool inspection, but the viewer does not read from it directly\n\nThat gives tools a stable place to inspect:\n\n- which surface is active\n- which artifact is the active entry\n- whether the runtime is `native`, `degraded`, or `closed`\n- whether native verification is currently possible\n- whether a write lock is held\n\n## Local Surface Security Defaults\n\nMicrocanvas is file-first, not a general-purpose hostile-content sandbox.\n\nCurrent defaults are intentionally narrow and honest:\n\n- source files may come from anywhere on the local filesystem, but must be direct readable local file paths and may not use unsupported schemes\n- symlinked source paths and symlinked ancestor directories are rejected by default during ingest\n- Microcanvas ingests caller-provided sources into runtime-owned `source/` paths before rendering or presentation\n- Markdown and wrapped code/text surfaces are sanitized before staging\n- raw HTML surfaces keep their original JS/CSS/layout behavior inside the ingested local surface copy\n- local web content can read only from the current ingested surface copy, so sibling assets must live alongside the source HTML to come through\n\nThat reduces obvious local-surface risk, but it does not claim to safely execute arbitrary untrusted web apps.\n\n## Known Barnacles\n\nMicrocanvas is usable early-stage software, so a few edges are still showing:\n\n- the native viewer path is currently macOS-first\n- only one active window and one active surface are supported at a time\n- `verify` and `snapshot` are intentionally strict about native viewer capability\n- unsupported formats fail clearly instead of being guessed into submission\n- the project is repo-first for now, while native viewer capability remains macOS-first\n\n## Agent Skill\n\nMicrocanvas ships with a tracked agent skill at `skills/microcanvas-present/` so agents use the CLI the way it is actually meant to be used.\n\nInstall local copies for common agent folders:\n\n```bash\nnpm run install:skills\n```\n\nUse the repo-local wrapper directly when you want deterministic behavior:\n\n```bash\nskills/microcanvas-present/scripts/run-microcanvas.sh show README.md --json\n```\n\nFor concrete agent flows, see `skills/microcanvas-present/references/cookbook.md`.\n\n## Development\n\n```bash\nnpm install\nnpm run build:viewer-app\nnpm run check\nnpm test\nnpm run pack:dry-run\n```\n\nThe current implementation is small on purpose. Surface detection and materialization run through the adapter registry in [`src/core/surface.ts`](src/core/surface.ts), which keeps format support explicit and easier to extend without turning the content model into soup.\n\n`npm run build:viewer-app` builds the SwiftPM viewer product and materializes `apps/macos-viewer/build/MicrocanvasViewer.app`. Generated app output is ignored; rebuild it locally when you need to test native launch behavior.\n\nWhen macOS viewer changes are involved and your environment supports it, run `cd apps/macos-viewer/MicrocanvasViewer \u0026\u0026 swift test`.\n\n## Contributing\n\nContributions are welcome. Start with [`CONTRIBUTING.md`](CONTRIBUTING.md) for the OpenSpec workflow, validation commands, and PR expectations.\n\n## Security\n\nIf you believe you found a security issue, please use the process in [`SECURITY.md`](SECURITY.md).\n\n## License\n\nMicrocanvas is available under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffraction12%2Fmicrocanvas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffraction12%2Fmicrocanvas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffraction12%2Fmicrocanvas/lists"}