Skip to content

[feat] canvas: download, import and pick the hosted example canvases - #390

Open
allendyu wants to merge 6 commits into
ThinkFlowLab:mainfrom
allendyu:feat/example-canvas-download
Open

allendyu wants to merge 6 commits into
ThinkFlowLab:mainfrom
allendyu:feat/example-canvas-download

Conversation

@allendyu

Copy link
Copy Markdown
Collaborator

Summary

Let the empty canvas offer a real example: pick one from a catalog, download it, unwrap whatever the host serves, import it through the existing archive path, and open it. A second entry in the project menu reaches the same picker, so trying another sample no longer means switching back to an empty canvas first.

  • Catalog (workspace/example/exampleCatalog.ts): strict per-row validation (https on an allowlisted host, unique id, bilingual title, digest/byte types, minAppVersion gate) with three tiers — remote catalog, the bundled public/example-canvases.json, then a compiled-in list. Unusable rows are reported and dropped instead of hiding the rest.
  • Download and normalization (exampleDownload.ts): streaming read under a byte budget, deadline and cancellation, optional outer and inner SHA-256 checks, and content-based format detection. The two shipped links deliver a ZIP wrapping exactly one .canvas, so the downloader unwraps one level and reports an HTML login page, a non-archive, or an ambiguous container separately instead of trusting the file name.
  • Picker (ExampleCanvasDialog.tsx, useExampleImport.ts): each row owns its status (downloading → importing → done), shows a live <progress> bar with the received bytes against the declared total, and can be cancelled. Cancelling before the bytes arrive returns the row to idle; cancelling after skips the import. A failed row keeps a manual-import fallback.
  • Cache release: the download exposes a release handle that zeroes the wrapper and unwrapped buffers, and the import calls it in a finally, so success, failure and cancel all leave no archive copy behind.
  • Reuse, not a second importer: importWorkspaceDocument and readCanvasArchive are the existing entry points; the transfer hook now exposes a throwing importCanvasArchive so the picker can classify the cause while the file-drop path keeps its toast behaviour.

Linked issue

No issue applies: this was scoped from a local design note rather than a repository issue. Happy to open a tracking issue if you prefer the work linked before merge.

  • Fixes #N or Refs #N is included, or no issue applies

Labels

  • Labels applied — type:feat, area:canvas, area:docs

Test plan

  • Local:
    • node --test tests/*.test.ts → 867/868. The only failure, browserHost "Python discovery supports PATH-only installs…", is pre-existing on clean main in this Windows environment (CJK temp path resolves as ALLEN_~1).
    • The three new suites (exampleCatalog, exampleDownload, exampleImport) → 36 passed, covering: catalog validation and three-tier fallback, ZIP-vs-canvas detection, ambiguous and nested archives, HTML bodies, size cap while streaming, declared content-length short-circuit, digests, progress events, and release on success/failure/cancel.
    • End-to-end against the two real links: both download (27.5 MB / 26.1 MB), unwrap to their .canvas (27.7 MB / 26.1 MB), and are read by readCanvasArchive — image: 12 nodes / 5 assets; video: 17 nodes / 9 assets. The recorded digests match.
    • tsc --noEmit clean; check-i18n 3061 keys 0 problems; check-browser-manifest 80 entries (gate=24); check-browser-locale 0 problems; vite build succeeds.
  • Left to CI: Release checks, including tests/browser/example_canvas_picker.mjs which is registered in the gate lane.

Evidence that it works

  • Media attached — both screenshots come from a local run of this branch.

The picker in dark mode (opaque panel, size only, no version column):

Example canvas picker

The new project-menu entry that reaches the same picker:

Project menu entry

Provider verification

  • Real-provider calls are described honestly, or none were made — none were made. The two samples are downloaded from a public HTTPS link (a third-party parser that redirects to a CDN); no model provider is involved. The model doubles in the browser fixture serve the isolated creation server only.

Bilingual UI

  • Both locales are updated — 27 canvas.example.* keys plus canvas.project.examples in zh-CN and en-US; user guides updated in both languages.

Notes for the reviewer

  • The hosted links are a third-party dependency. They resolve lanzou shares through lz.qaiu.top to a Qiniu CDN path that contains a date. The catalog therefore stores the parser URL (not the CDN URL) and always re-resolves on click (cache: "no-store"). If a link dies, the row reports the failure and offers manual import; swapping links is a catalog-field change only. Moving the two .canvas files to our own object storage would remove this dependency.
  • The browser check could not run locally: this machine cannot fetch a Chromium build (the Playwright CDN is unreachable and the cached archive is truncated), so the gate-lane check is written and registered but unverified here. I did not mark it as run.
  • minAppVersion filtering is inert until the frontend exposes its own version; unknown versions skip the gate rather than hiding every sample.

## summary

- Add `exampleCatalog.ts`: strict per-row validation (https on an allowlisted
  host, unique id, bilingual title, digest/byte types, `minAppVersion` gate)
  with three-tier loading — remote catalog, then the bundled copy, then a
  compiled-in list — so a missing file or an offline launch still offers the
  samples. Unusable rows are reported and dropped instead of hiding the rest.
- Add `exampleDownload.ts`: https-only allowlist, streaming body read under a
  byte budget, deadline and caller cancellation, optional outer and inner
  SHA-256 checks, and content-based format detection. The shipped links deliver
  a ZIP wrapping exactly one `.canvas`, so the downloader unwraps one level and
  reports HTML login pages, non-archives and ambiguous containers separately
  rather than trusting the file name.
- Ship both samples in `public/example-canvases.json` with the sizes and
  digests measured against the live links on 2026-11-17.
- Keep the import call site untouched; the dialog that uses these modules and
  the `readCanvasArchive` hand-off follow in the next commit.

## validation

- `node --test tests/exampleCatalog.test.ts tests/exampleDownload.test.ts`:
  25 passed.
- `tsc --noEmit` clean; `pre-commit run` clean after the hook normalized line
  endings.
- Full frontend suite 856/857; the only failure is the pre-existing
  `browserHost` CJK temp-path case that also fails on clean `main`.
- Manual end-to-end against the shipped links: both downloaded, unwrapped and
  read by `readCanvasArchive` (image: 12 nodes/5 assets; video: 17 nodes/
  9 assets), which also proves the recorded outer and inner digests.
## summary

- Add `ExampleCanvasDialog`: a native `<dialog>` listing the catalog with the
  localized title, summary, size and archive version. Each row owns its status,
  so one failing sample never blocks the others.
- Add `useExampleImport` and `runExampleImport`: download, hand the unwrapped
  archive to the caller's import path, and report `downloading → importing →
  done`. Cancelling during download returns the row to idle instead of showing
  an error, and a cancel that lands after the bytes arrive skips the import
  entirely.
- Keep the archive out of component state: the blob is created for the import
  call and dropped afterwards, so no downloaded copy survives the import.
- Classify failures for the reader — HTTP status, blocked page, non-archive,
  ambiguous container, digest mismatch, untrusted address — instead of showing
  one generic message.
- Add an explicit manual-import fallback per row (share link plus code) for
  cases the hosted link itself is gone.
- Add the 27 bilingual strings and register the catalog's Chinese sample names
  in `scripts/i18n-baseline.json`: they are data, not translatable UI copy.

## validation

- `node --test tests/exampleImport.test.ts tests/exampleCatalog.test.ts
  tests/exampleDownload.test.ts`: 30 passed.
- `tsc --noEmit` clean; `check-i18n` 0 problems; `pre-commit run` clean after
  the hook normalized line endings.
- Full frontend suite 861/862; the only failure is the pre-existing
  `browserHost` CJK temp-path case that also fails on clean `main`.

## notes

- The dialog is not rendered yet; wiring the empty-state button and the
  `readCanvasArchive` hand-off is the next change.
## summary

- Wire the empty-state button to the picker: clicking "try the example canvas"
  loads the catalog and opens the dialog directly, so a fresh install with no
  local sample still has something to open.
- Split the archive import in `useWorkspaceTransfer`: `importCanvasArchive`
  reads the archive, lands it as a project and returns the title/asset count
  while throwing on failure; `importDocument` keeps the toast-and-notify
  behaviour the file drop path already had. The picker uses the throwing
  variant so its own classifier can name the cause.
- Leave the running version out of the `minAppVersion` gate: the frontend does
  not expose its own version yet, and filtering on an absent value would hide
  every sample. The gate still applies once a version is supplied.
- Show the localized archive error when a failure has no dedicated code
  (for example "archive is newer than this app") instead of a generic message.
- Keep the in-browser generated example and its `openExampleWorkspaceProject`
  recovery path intact for the paths that still use them.

## validation

- `node --test tests/*.test.ts`: 862/863 passed. The only failure is the
  pre-existing `browserHost` CJK temp-path case that also fails on `main`.
- `node --test` on the three example suites: 31 passed.
- `tsc --noEmit` clean; `check-i18n` 0 problems; `pre-commit run` clean.
- `vite build` succeeds and the output contains the dialog markup, the built-in
  catalog and `dist/example-canvases.json` with both entries, so the compiled
  fallback ships with the app.

## notes

- The picker is clickable from the empty canvas now; a browser test that drives
  the download, the failure codes and the cache release follows next.
…he gate lane

## summary

- Release the download explicitly: `fetchExampleCanvas` now returns a `release`
  handle that zeroes the wrapper and the unwrapped buffers, and
  `runExampleImport` calls it in a `finally`, so success, failure and cancel all
  leave no archive copy behind. The import result carries only metadata
  (`kind`, `innerEntry`, `outerBytes`), never the bytes.
- Add `tests/browser/example_canvas_picker.mjs` and run it from
  `scripts/run-browser-suite.mjs` in the `gate` lane. It builds the fixture with
  the real exporter, serves it as a ZIP around one `.canvas`, and asserts: the
  empty canvas opens the picker, the wrapped download imports and switches to a
  two-node canvas, and an HTML page is reported without creating a project while
  the manual-import fallback stays reachable. Both the catalog and the sample
  are routed in-page, so the check needs no external host.
- Document the picker in both user guides, including the ZIP-around-`.canvas`
  unwrapping and the manual fallback.

## validation

- `node --test tests/*.test.ts`: 864/865. The only failure is the pre-existing
  `browserHost` CJK temp-path case that also fails on `main`.
- The three example suites: 33 passed, including the new release assertions
  (buffers zeroed, idempotent, released on success and on import failure).
- `tsc --noEmit` clean; `check-i18n` 0 problems; `check-browser-manifest`
  `80 entries, gate=24`; `check-browser-locale` 0 problems; `pre-commit` clean.

## verification limit

- The browser check was **not executed here**: this machine cannot download a
  Chromium build (the Playwright CDN is unreachable and the cached archive is
  truncated). The manifest and locale checks confirm it is registered and
  synthesised correctly; the gate lane runs it on CI.
…ow progress

## summary

- Fix the dark-mode overlap: the picker used `--cw-control-*`, which the app
  only defines under `[data-theme="light"]`, so in the default dark theme the
  dialog had no background and the empty canvas showed through its text. Dark
  colours are now the base and the light theme overrides them, matching how the
  other dialogs are themed. The backdrop is opaque enough to stop the bleed.
- Drop the archive version from each row; the row now shows only the measured
  size. The size/version message keys are removed in both locales.
- Show real download progress: the streaming reader reports received bytes and
  the declared total, the import status carries them, and the row renders a
  native `<progress>` bar with a percentage. When the server sends no
  `content-length` the bar stays indeterminate instead of inventing a total.
- Release the download as soon as the import settles (success, failure or
  cancel), so the progress work does not leave a second copy behind.

## validation

- `node --test tests/*.test.ts`: 867/868. The only failure is the pre-existing
  `browserHost` CJK temp-path case that also fails on `main`.
- The three example suites: 36 passed, including new assertions that progress
  starts at 0 with the declared total, ends at the full size, and reports an
  unknown total when the header is absent.
- `tsc --noEmit` clean; `check-i18n` 0 problems; `check-browser-manifest` and
  `check-browser-locale` clean; `vite build` succeeds and the emitted CSS now
  carries `background:#23242b` for the dialog.

## notes

- The browser check still runs only on CI; this machine cannot fetch a
  Chromium build.
## summary

- Add an "example canvases" row to the project menu, above "new canvas
  project". It opens the same picker the empty canvas offers, so choosing
  another sample no longer requires switching back to an empty canvas first.
- Reuse the existing footer row styling instead of a new block, and close the
  menu before loading the catalog so the dialog is not stacked under it.
- Extend the gate browser check: after closing the picker once, it opens the
  project menu, chooses the new row and asserts the picker comes back.

## validation

-
ode --test tests/*.test.ts: 867/868. The only failure is the pre-existing
  �rowserHost CJK temp-path case that also fails on main.
- 	sc --noEmit clean; check-i18n 3061 keys, 0 problems;
  check-browser-manifest and check-browser-locale clean; �ite build
  succeeds.

## notes

- The browser check still runs only on CI; this machine cannot fetch a
  Chromium build.
@allendyu allendyu added area:canvas Canvas, nodes and direct manipulation area:docs Documentation / 文档 type:feat New capability or behaviour labels Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:canvas Canvas, nodes and direct manipulation area:docs Documentation / 文档 type:feat New capability or behaviour

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant