Skip to content

[feat] web: register stage stills and preview MP4s as assets - #330

Draft
MrDongsls wants to merge 35 commits into
ThinkFlowLab:mainfrom
MrDongsls:feat/stage-output-assets
Draft

MrDongsls wants to merge 35 commits into
ThinkFlowLab:mainfrom
MrDongsls:feat/stage-output-assets

Conversation

@MrDongsls

@MrDongsls MrDongsls commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Refs #241

Summary

Director Stage outputs become project assets, and published preview outputs keep only local video tools on the canvas toolbar. Slice 3 of 4 delivering #241, stacked on #329.

Output registration:

  • Director documents pin a captured still asset; the save projection imports captured bytes as project image assets, and reopening restores the node thumbnail from the asset instead of a data URL.
  • The preview MP4 publishes through canvas.publishMedia with a frozen director execution snapshot; the output video asset carries provenance.source = 'rendered' plus the execution document identity, and timeline clips reference the published assetId directly. Refused editor deliveries are released instead of being replayed, so retries do not duplicate entries.

Toolbar semantics for preview outputs:

  • The projection resolves a rendered asset's execution document and stamps stagePreview only for director documents (src/backend/creationProjection.ts); timeline renders share the rendered source but are ordinary composition outputs and are not affected.
  • The shared contract holds the exclusion set STAGE_PREVIEW_EXCLUDED_VIDEO_TOOLS (src/canvas/toolCatalog.ts); the selection toolbar derives from it. A published preview keeps frame capture, trim, crop, and universal actions; generative and audio tools (partial reshoot, upscale, video edit, extend, depth capture, separate audio, interpolation, subtitle erasure, matting) are gone. Ordinary video nodes keep the full toolbar.

Linked issue

Labels

  • type:feat, area:canvas

Test plan

  • Local, run at this PR's head: npx tsc --noEmit clean; npm test 697/697; npm run check:i18n 0 problems; .venv/bin/python -m pytest tests/test_director_stage_assets.py tests/test_creation_media_publication.py tests/test_creation_director.py 37 passed; node tests/browser/director_stage_output.mjs passes (still and MP4 register as assets, timeline references the published assetId, reload persists); node tests/browser/director_stage_delivery.mjs passes (a refused stored delivery is released, not replayed).
  • Left to CI: full pytest suite, Release checks.
  • Not run: nothing outstanding for this slice.

Evidence that it works

  • The same preview node on the isolated backend, before (this stack's parent head, full toolbar) and after (this head):
    before: before
    after: after

Provider verification

  • No real-provider calls; rendering, stills, and registration are local.

Bilingual UI

  • New copy ships zh-CN and en-US together; check:i18n reports 0 problems. The toolbar was also inspected in both locales on a live project.

- Enable the Director Stage entry in the shared creation toolbar and
  open the stage editor automatically after creating the node.
- Pin node, document, and keyframe identity across editor.save, undo,
  redo, and storage reload with a service-level command test.
- Add a browser acceptance flow covering creation, editing, undo,
  redo, and reopen, runnable in en-US and zh-CN via
  DIRECTOR_STAGE_LOCALE.

- npm test (676 passing at this commit's tree state).
- .venv/bin/python -m pytest tests/test_creation_director.py.
- node tests/browser/director_stage_entry.mjs plus the
  DIRECTOR_STAGE_LOCALE=zh-CN run, against the isolated
  creation_server.py fixture.

Refs: ThinkFlowLab#241
## summary

- Extend StageObject with kind 'gltf' carrying a registered AssetRef,
  a character or scene role, a glb or gltf container format, and the
  animation clip names discovered in the imported asset.
- Reject incomplete or incompatible imports at the contract boundary:
  missing asset, role, or format, non-file assets, motion clips on
  scene assets, motion without animation data, mismatched animation
  flags, and blank animation names.
- Prove the persistence boundary with a command-level test: forged
  asset references are rejected without state changes and replays
  return the original receipt.

## validation

- .venv/bin/python -m pytest tests/test_director_stage_assets.py
  tests/test_creation_contracts.py (89 passing at this commit's tree
  state).
- .venv/bin/python scripts/generate_contracts.py --check.
- npm test (676 passing) and npm run build against the old projection
  reading the regenerated contract fixture.

Refs: ThinkFlowLab#241
## summary

- Import GLB and self-contained GLTF files as stage objects with a
  character or scene role; FBX files and GLTF resources with external
  dependencies are rejected with bilingual capability notices.
- Keep blob preview URLs out of persisted identity: saves register the
  imported file as a project asset and the stage object pins its
  AssetRef, so imported objects survive reopen, undo, and redo.
- Surface per-object capability boundaries in the editor: static use
  without animation data, discovered clip names, and motion clips only
  when the asset carries animation data.

## validation

- npm test (679 passing) and
  .venv/bin/python -m pytest tests/test_director_stage_assets.py
  tests/test_creation_contracts.py tests/test_creation_director.py.
- .venv/bin/python scripts/generate_contracts.py --check and
  npm run check:i18n (2888 keys, 0 problems).
- node tests/browser/director_stage_entry.mjs plus the
  DIRECTOR_STAGE_LOCALE=zh-CN run against the isolated
  creation_server.py fixture.

Refs: ThinkFlowLab#241
## summary

- Detect GLB and GLTF containers from actual bytes during upload
  probing, record model/gltf-binary or model/gltf+json MIME types,
  and mark whether every buffer and image is embedded in a new
  selfContained metadata flag.
- Reject director documents whose imported stage objects pin assets
  that are not self-contained models of the declared container
  format, so no entry point can smuggle external-resource files into
  a stage document.

## validation

- Verified on the full model import and animation tree:
  .venv/bin/python -m pytest tests (1096 passed, 6 skipped) and
  .venv/bin/python scripts/generate_contracts.py --check.

Refs: ThinkFlowLab#241
…mations

## summary

- Probe import bytes in the editor: the container format comes from
  the GLB header or GLTF document, not the file extension, and corrupt
  or external-resource files are rejected with localized notices
  before anything reaches the project.
- Map procedural motion presets onto imported animation clips through
  shared name hints in stageMotion, so preview, stills, and MP4
  rendering pick the same clip from the same stage sampling.
- Cover the flow end to end with an animated GLB fixture: clip
  discovery, motion binding at the playhead, playhead scrub
  animation, and a 1280x720 MP4 rendered through the shared sampler.

## validation

- Verified on the full model import and animation tree: npm test
  (680 passing), npm run build, npm run check:i18n, and the isolated
  browser checks tests/browser/director_stage_entry.mjs (en-US and
  zh-CN) and tests/browser/director_stage_animation.mjs.

Refs: ThinkFlowLab#241
…l capture

## summary

- renderVideo parsed the stage into a local `snapshot` that shadowed
  the component's `snapshot()` still-capture helper; rename the local
  to `exportStage` so the two are no longer confused.
## summary

- stopAllAction leaves imported skeletons frozen at the last sampled
  pose; capture the authored rest pose when a runtime binding is created
  and restore it whenever a sample leaves a motion clip.
- Build preview and export bindings through one createImportedRuntime
  helper, and clone export runners from the pristine cached scene so
  frames outside clips render the authored rest pose too.
…sources

## summary

- A GLB whose header is valid but whose embedded JSON chunk is missing,
  unparsable, or not a glTF document was reported as an unsupported
  external-resource import; probeStageAsset now returns a distinct
  corrupt result with its own bilingual message.
- Move the byte probe next to the stage document format and export it
  so container checks are testable without a browser.
## summary

- The director projection derived upload names as `${name}.${format}`;
  renaming a stage object to "hero/v2" made the whole save fail on the
  backend path-character check. Derive through stageUploadTitle, which
  replaces path separators and control characters, trims, caps the
  length under the 255-character upload limit, and falls back to the
  localized model title for blank names.
- Cover the sanitization with Node tests.

## validation

- node --test tests/directorStageAssets.test.ts
## summary

- The .gltf probe read whole files into memory under only the generic
  512 MiB asset cap. inspect_file now rejects GLB and .gltf uploads
  above MAX_STAGE_MODEL_BYTES (100 MiB, matching the browser import
  limit) with a bilingual 413 before any full read.
- Oversized JSON without a .gltf suffix is no longer parsed as a
  document and stays a generic file instead of spiking memory.
- Cover oversized GLB, oversized .gltf and oversized plain JSON.

## validation

- .venv/bin/python -m pytest tests/test_director_stage_assets.py -q
## summary

- The load effect cached resolved scenes only; while a slow load was in
  flight, a re-run fetched the same asset again and the loser's scene
  was overwritten in the cache without ever being disposed, leaking its
  WebGL buffers. Cache the in-flight promise under the cache key so
  concurrent runs share one load.
- Evict a promise from the cache when it rejects so later runs can
  retry, and dispose resolved scenes on unmount through the promise.
## summary

- StageObject.animationNames and hasAnimation were client-attested and
  never compared with the pinned asset. The upload probe now records the
  animation names a model container declares (declared names trimmed,
  unnamed clips falling back to animation_{index}, matching what the
  browser loader derives) as MediaMetadata.animationNames, and snapshot
  validation rejects stage objects whose animation metadata disagrees
  with the pinned asset bytes.
- Align the front-end unnamed-clip fallback with the same convention.
- Regenerate contracts, extend the fixture and cover forged names and
  the fallback naming with Python tests.

## validation

- .venv/bin/python -m pytest tests/test_director_stage_assets.py
  tests/test_creation_contracts.py -q
- .venv/bin/python scripts/generate_contracts.py --check
- npm exec tsc -- --noEmit
## summary

- Exported stage JSON keeps pinned asset identity but carries no model
  bytes, so importing it into another project produced objects that
  could neither preview nor apply: the editor showed an unavailable
  asset and every save failed the backend asset check until the objects
  were deleted by hand.
- The workspace now passes the open project's registry to the stage
  editor (same consistency the backend snapshot check demands), and
  import rejects up front with a bilingual message naming the objects
  whose assets are not registered in this project.
- Cover the foreign/registered/unregistered distinction with Node tests.
## summary

- Python: a GLB with a valid header whose declared length exceeds the
  file stays a generic file asset, and stage objects pinning it are
  rejected.
- Node: byte-level cases for the shared stage asset probe (self-contained
  and external models, truncated GLB, corrupt or non-document JSON
  chunks), and a projection read where the pinned model's content is
  unavailable — the reopened stage keeps its registered asset identity
  and stays a valid document without the preview URL.

## validation

- .venv/bin/python -m pytest tests/test_director_stage_assets.py -q
- node --test tests/directorStageAssets.test.ts
- npm exec tsc -- --noEmit
## summary

- Add zh-CN text to all seven StageObject import validation errors in
  the domain contract, matching the dual-language pattern already used
  by the stage checks in project.py.
- Chinese wording follows the stage terminology in the editors message
  catalogs (舞台对象, 素材, 动作片段), so receipt issues stay readable
  in both locales.
- Validation rules and error conditions are unchanged; only the
  message text now carries both languages.

## validation

- .venv/bin/python -m pytest tests/test_director_stage_assets.py
  tests/test_creation_director.py tests/test_creation_contracts.py
  (98 passed, working tree identical to the staged content)
…d pin procedural rejects

## summary

- Deliver the missing-or-inconsistent pinned asset reference
  rejection in both Chinese and English, matching the other snapshot
  boundary messages.
- Cover procedural stage objects that carry imported asset or
  animation metadata, which the stage object contract rejects.

## validation

- Verified on the full still and MP4 registration tree:
  .venv/bin/python -m pytest tests/test_director_stage_assets.py
  tests/test_creation_contracts.py.

Refs: ThinkFlowLab#241
…daries

- Probe glTF documents for Draco, meshopt and KTX2 extensions and reject
  them with a bilingual notice for needing decoders the browser loader
  cannot provide, instead of mislabeling the bytes as corrupt.
- Route stage and layer JSON imports through a text boundary that reports
  unparsable files (including binary model bytes fed to the JSON picker)
  with a localized notice instead of an engine SyntaxError quoting them.
- Keep cached imported scenes resident while any live clone references
  them, and dispose them only after the last one is gone.
- Share one selection-highlight pass across placeholder and imported
  clones so unlit materials without emissive survive selection.
- Preserve the loader's animation_{index} fallback for unnamed imported
  clips in committed metadata, and stream-scan leading whitespace before
  glTF JSON heads in the upload probe (also catching pathological deeply
  nested JSON via RecursionError).

- Verified on the staged tree: node_modules/.bin/tsc --noEmit,
  node --test tests/canvasStage.test.ts tests/directorStageAssets.test.ts
  tests/layerDocument.test.ts (32 passing), and
  PYTHONPATH=packages/core/src .venv/bin/python -m pytest
  tests/test_director_stage_assets.py (26 passed).
… retargeting

## summary

- Route every stage numeric field through one NumberField text-to-value
  boundary: only canonical decimal text commits, so leading zeros ("03"),
  trailing dots, exponents and empty input never become values and a
  cleared field can no longer silently write 0.
- Replace the read-only time readout with an editable current-time field,
  clamped to [0, duration] and quantized to hundredths so the playhead,
  the slider and keyframe identity share one time grid.
- Extract stageCameraAt as the single shot-resolution source shared with
  the sampler: choosing an edit-target camera or duplicating a camera no
  longer flips cameraSource off storyboard cuts, and in storyboard mode
  the selection retargets the shot covering the playhead instead.

## validation

- Verified on the staged tree: node_modules/.bin/tsc --noEmit, node --test
  tests/canvasStage.test.ts (14 passing, including stageCameraAt boundary,
  gap and clamping coverage), and npm run check:i18n (2896 keys,
  0 problems).
- node tests/browser/director_stage_entry.mjs covers the numeric contract,
  clamped quantized playhead entry, and storyboard-preserving camera
  selection end to end in both locales.
## summary

- Split Director Stage scrolling into two regions — subjects with the
  stage and timeline on one side, the inspector on the other — so neither
  column drags the other along. Region scrollbars stay thin and quiet
  until the region is hovered or dragged; narrow layouts (<=1100px) keep
  the previous single shared scroll.
- Size the stage frame to a comfortable centered width (900px for 16:9)
  shared by the viewport, transport, playhead track, keyframes and
  storyboard, so the draggable track lines up exactly with the picture
  instead of overrunning it, and portrait stages stay height-capped and
  centered.
- Pin the footer hint below the two regions instead of letting it ride
  inside the layout container, where it could drift off the page once the
  layout became position-managed.

## validation

- Verified on the staged tree: node_modules/.bin/tsc --noEmit and
  npm test (693 passing).
- Measured in the browser across 1920x1080, 1440x900, 1229x691, 1280x720,
  1366x640, 1100x700 and 1000x620 viewports: the frame stays centered with
  the track exactly matching its width, both regions scroll independently,
  the bottom action bar and hint remain inside the window, and narrow
  viewports fall back to one scroll.
- node tests/browser/director_stage_entry.mjs passes in en-US and zh-CN
  after the restructure.
- Add an optional still field to DirectorData that pins the captured
  frame as a project image asset, so the still survives reopen with a
  real identity instead of an untracked node data URL.
- Reject director documents whose still pins a missing or non-image
  asset at the snapshot boundary, alongside the existing model checks.
- Cover the field with service tests for round-trip, dangling
  references, and non-image rejections.

- Verified on the full still and MP4 registration tree:
  .venv/bin/python -m pytest tests (1104 passed, 6 skipped) and
  .venv/bin/python scripts/generate_contracts.py --check.

Refs: ThinkFlowLab#241
- Capture stage stills at the encoder aspect through the same sampler
  as the MP4 render: the first apply auto-captures a poster, later
  applies keep the pinned still, and an explicit capture registers a
  distinct image asset while the previous one stays registered.
- Route stills through the save projection: captured bytes are
  imported as project image assets, the director document pins the
  resulting AssetRef, and reopening restores the node thumbnail from
  the asset instead of a data URL.
- Audit the director MP4 path: published documents freeze a copy of
  the director document with its source editor identity.
- Cover the chain end to end: still capture, no-overwrite semantics,
  MP4 output nodes pinning real video assets, timeline clips
  referencing the published assetId, and reload persistence.

- Verified on the full still and MP4 registration tree: npm test (685
  passing), npm run build, npm run check:i18n (2891 keys, 0 problems),
  and the isolated browser checks director_stage_output.mjs,
  director_stage_entry.mjs (en-US and zh-CN), and
  director_stage_animation.mjs.

Refs: ThinkFlowLab#241
- Capture stills at exactly the encoder resolution on high-DPI
  displays by pinning the renderer pixel ratio during capture.
- Clone the export scene only after render preparation so a model
  whose preview load lands mid-preparation no longer exports as its
  placeholder, and dispose placeholder-owned GPU resources.
- Reject stage JSON exports that contain imports lacking registered
  assets, seed the shared asset cache during import to avoid double
  parses, widen the upload probe for whitespace-prefixed glTF
  documents, and count surrogate pairs when truncating upload titles.
- Hide the material color picker for imported models and verify the
  still dimensions under a doubled device scale factor.

- Verified on this tree: npm test (688 passing),
  .venv/bin/python -m pytest tests/test_director_stage_assets.py
  tests/test_creation_contracts.py, npm run build, and
  npm run check:i18n (2892 keys, 0 problems).

Refs: ThinkFlowLab#241
…aying them

## summary

- Treat a transport-level 4xx refusal (400, 401, 403, 413, 422) on an
  editor delivery as definitive, the same as a command rejection: the
  stored pending plan is dropped instead of being replayed forever from
  sessionStorage. A plan prepared by an older schema (for example one the
  current backend rejects with 422 invalid_input at the HTTP boundary)
  now costs at most one failed attempt before the next one replans with
  current code; unknown replies and lost responses keep their retained
  delivery and replay the exact same command.

## validation

- Verified on the staged tree: npm test (693 passing) including a unit
  test that seeds a refused stored delivery and asserts it replays once
  and replans on the retry.
- node tests/browser/director_stage_delivery.mjs reproduces the reported
  stuck Director Stage end to end: a poisoned stored delivery surfaces
  the error once, the next render replans and completes the MP4, and
  apply recovers over the same stored entry.
- Derive a stagePreview flag at projection by resolving a rendered
  asset's editor document to its director execution snapshot, so
  timeline composition renders keep the full toolbar.
- Add STAGE_PREVIEW_EXCLUDED_VIDEO_TOOLS to the shared tool catalog
  and filter the video selection toolbar through it; preview outputs
  keep frame capture, trim, crop, and universal actions only, while
  ordinary video nodes are unchanged.
- Accept the optional flag in archive provenance validation and cover
  the exclusion set, predicate, and projection stamping with tests.

- npx tsc --noEmit; npm test (697 passing); npm run check:i18n
  (0 problems).
- .venv/bin/python -m pytest tests/test_creation_media_publication.py
  tests/test_creation_canvas_service.py (33 passing).
- Browser: selected the published preview node in the live project and
  read the toolbar in both zh-CN and en-US.
@MrDongsls
MrDongsls force-pushed the feat/stage-output-assets branch from bf7f98a to 5b92874 Compare November 15, 2026 03:36
@MrDongsls
MrDongsls marked this pull request as ready for review November 15, 2026 05:08
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-15T05:23:33.112665Z 8733eef Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions github-actions Bot added the area:docs Documentation / 文档 label Nov 15, 2026
@github-actions
github-actions Bot requested a review from wuzhf9 November 15, 2026 05:09

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8733eef75b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src: node.data.stillCapture,
fresh: true,
})
: node.data.stillAsset;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Re-home pinned stills when pasting stages across projects

After applying a stage so it has a stillAsset, copying it into another project leaves this reference pointing into the source project. transferClipboardMedia() registers the thumbnail in the target and rewrites src/backendAssetId, but does not rewrite stillAsset; this branch then sends the original pin to the backend, where ProjectSnapshot rejects the target canvas save as a missing pinned asset. Re-pin the still to the asset registered in the target project before saving.

AGENTS.md reference: AGENTS.md:L45-L45

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 3602caf. Cross-project pastes now re-home stage media: transferClipboardMedia captures imported-model bytes at copy time and registers them in the target project (server-side copyAsset preferred for saved pins), rewrites the pasted node's stillAsset and each gltf object's asset pin to the registered copies, and drops the carried stillCapture once the re-homed pin replaces it. A pin whose bytes are unreachable fails the paste loudly instead of inserting a reference the backend would reject. Covered by unit cases in tests/directorStageAssets.test.ts and the cross-project paste lane in tests/browser/director_stage_media_travel.mjs.

Comment thread src/canvas/DirectorStage.tsx Outdated
Comment on lines +1259 to +1262
scene = previewRuntime.scene.clone(true);
const root = scene.getObjectByName("stage-objects")!;
const renderImported = new Map<string, ImportedRuntime>();
for (const [id, binding] of previewRuntime.imported) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Wait for imported models before freezing the render scene

If Render MP4 is clicked after reopening a stage while an imported model is still loading, ready is already true and onPrepareRender() only waits for the document save. This clone therefore captures the model's placeholder, and the following loop only replaces models already present in previewRuntime.imported. A later successful load cannot update the cloned scene, so the placeholder is permanently encoded and can be published against the full director snapshot. Await every model required by exportStage, and reject rendering if any load fails.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 878a9d8. renderVideo now awaits every gltf object's assetCache entry before the scene is cloned, refuses the render with the localized assetLoadFailed when a model is unavailable or failed, and replaces models for every export object from the pristine cached scene (in-flight loads that had not reached previewRuntime.imported included). The browser lane covers an 8-second-delayed fetch (the render completes only after the bytes are released) and a 404 (error shown, no MP4 encoded, no publication).

Comment thread src/backend/creationProjection.ts Outdated
Comment on lines +420 to +422
source: await this.client
.mediaUrl(object.asset.assetId)
.catch(() => undefined),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Include stage model resources in canvas archives

For a saved stage containing a GLB/GLTF object, mediaUrl() puts a blob: URL in this new source field. However, canvasArchive.ts:23 only recognizes src, sourceImageUri, and output as media fields, so buildCanvasArchive() leaves the model URL untouched and rejects the entire export with transientMedia. This is reproducible with a registered model: adding one supported model makes Export Canvas unusable. Bundle the model bytes and re-home their pinned references during archive import rather than retaining browser URLs and source-project identities.

AGENTS.md reference: AGENTS.md:L45-L45

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in eaa47f8. Exports register gltf sources as archive assets through a stage-media visitor shared with the clipboard path, so a saved model no longer trips transientMedia; archives containing stage documents declare format v4 so older readers reject them explicitly instead of degrading silently. Import restores model bytes inline, drops the exporting project's pins, and converts the bundled still preview into the carried stillCapture so the importing project's save re-registers both. A saved pin whose bytes can no longer be read refuses the export with the new bilingual errors.archive.stageMediaMissing. Round trip covered in unit tests and the archive lane of the browser script.

Comment on lines +1115 to +1118
const next = parseLocalStageDocument(await file.text(), t);
const foreign = isRegisteredAsset
? unregisteredStageAssets(next, isRegisteredAsset)
: [];

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Resolve pinned model URLs when importing stage JSON

Importing a stage JSON exported from this same project passes this registration check but cannot reconstruct its models. Export stage JSON deliberately removes each object's source, while this import path installs the parsed objects without resolving their retained asset references. The loading effect then reports assetUnavailable and leaves placeholders even though the assets are registered and readable. Resolve the pinned assets to preview URLs before installing the imported stage, or make the loader resolve asset references directly.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in e4155d3. The workspace now passes resolveStageAssetSource (backed by creationClient.mediaUrl) into the stage, and the load effect resolves a pinned asset that carries no live preview URL before falling back to the existing assetUnavailable notice, covering both stage JSON imports and reopened projects. The same commit replaces the projection's silent catches with an explicit assetState of ready/missing on the director node plus a bilingual missing-media notice, so an unreadable still or model surfaces instead of an unexplained empty scene.

Comment thread src/canvas/DirectorStage.tsx Outdated
Comment on lines +237 to +239
for (const material of materials)
if (material instanceof THREE.MeshStandardMaterial)
material.emissive.set(highlighted ? "#1e1536" : "#000000");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve authored emissive values on imported materials

For a supported GLB/GLTF whose materials have a nonzero emissiveFactor, this selection update overwrites the authored emission with either the selection tint or black. Imported clones share their materials with the cached scene, so the original values are also lost there, and renderVideo() explicitly zeros emission again. Consequently, both captured stills and MP4s can lose emissive details or render emissive-only surfaces black. Preserve the authored emission separately and apply selection highlighting without destroying it.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 612e6a9. Authored emissive color and intensity are recorded once per asset load into the shared materials (SkeletonUtils clones see the same record), selection tints at intensity one while selected and restores the authored values when deselected, and the export's private material clones restore instead of zeroing. Pixel-probed in the browser lane: the strongest red-minus-blue pixel of the captured still exceeds 60 at the new head and reads 0 at 8733eef, reproducing the finding on the baseline.

Comment thread src/canvas/NodeFrame.tsx Outdated
className="cw-port cw-proxy-port"
/>
)}
{nodePorts(kind).source && (

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep source proxy handles for stage publication edges

When a stage preview is published, CreationProjection.read() still creates a post_edit_result edge from the external stage to its output (creationProjection.ts:950-954). Since nodePorts("external").source is now false, this conditional removes the stage's only source handle. React Flow requires that handle before it mounts the custom edge, so the published stage-to-output relationship no longer renders. Retain the non-connectable proxy handle for provenance edges while separately disabling interactive generation-reference creation.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in a10e77e. External stage nodes mount the existing non-connectable proxy handles in both directions, since the stage's assembly-input edges target the node as well and a node with no handle at all blocks every edge touching it, not only post_edit_result. nodePorts stays the interactive connection policy, so no new interactive references become possible. The browser lane asserts the published stage's provenance edge renders in the canvas.

@Probiotics5333

Copy link
Copy Markdown
Collaborator

Not repeating the six Codex findings — they are real, and the three P1s (cross-project stillAsset re-homing, rendering before imported models finish loading, archive export rejected as transientMedia) should be resolved before this merges. Two additional points from the projection path:

1. Projection silently swallows missing assets. mediaUrl(...).catch(() => undefined) is used for both doc.data.still and a gltf object's asset. When an asset is unavailable the stage opens as an empty scene with a missing thumbnail and no explanation. This is adjacent to, but distinct from, the Codex point about stage JSON import not resolving assets: that one is the import path, this one swallows the error on every projection rebuild. Surfacing assetState: 'missing' to the stage UI, or at least a warning, would make the failure diagnosable.

2. Is fresh: true intended on every save? still goes through importResource({ fresh: true }) each time the director document is projected. Within one session the imported cache keyed on the data URL prevents duplicates, but if stillCapture remains on the node after a save, reopening the project (fresh client, empty cache) and saving again would register a second image asset for the same still. Confirming whether stillCapture should be cleared after a successful save would settle it.

## summary

- Register imported stage models and the pinned still in the target
  project when a director node is pasted across projects, reusing the
  clipboard's captured bytes and preferring server-side asset copies.
- Rewrite the pasted node's stillAsset and each gltf object's asset pin
  to the registered copies so the target save passes pin validation;
  drop the carried stillCapture once the re-homed pin replaces it.
- Fail the paste when a stage pin's bytes are unreachable instead of
  inserting a reference the backend rejects; keep the capture fallback
  when only the still pin is unreadable.

## validation

- node --test tests/directorStageAssets.test.ts
  tests/clipboardMedia.test.ts tests/timelineText.test.ts
- npx tsc --noEmit
## summary

- Register imported stage models as archive assets on export so a saved
  gltf source's blob URL no longer aborts Export Canvas as transient
  media; archives carrying stage documents now declare format v4, which
  older readers reject explicitly instead of degrading silently.
- Restore model bytes to inline data URLs on import and drop the
  exporting project's asset pins, so the importing project's save
  re-registers the models instead of failing pin validation.
- Convert the bundled still preview into the carried stillCapture for
  the same re-registration, and refuse exports whose saved stage pins
  can no longer be read (new bilingual errors.archive.stageMediaMissing).

## validation

- node --test tests/directorStageAssets.test.ts tests/canvasArchive.test.ts
- npm run check:i18n
- npx tsc --noEmit
## summary

- Await every gltf asset the export needs through the shared asset cache
  before the scene is cloned, so a model whose preview load is still in
  flight can no longer be encoded as its permanent placeholder.
- Refuse the render when any model is unavailable or failed to load,
  naming the object with the existing assetLoadFailed message; no MP4 is
  encoded, registered or published in that case.
- Replace models from the pristine cached scene for every export object
  instead of only those already installed in the preview runtime, and
  drop the stale comment claiming preparation ordering solved the
  placeholder race.

## validation

- npx tsc --noEmit
- node --test tests/canvasStage.test.ts tests/stagePreviewVideoTools.test.ts
- No unit test for the wait itself: DirectorStage.tsx is JSX, which the
  node test runner cannot import; browser lane covers the slow-load and
  failing-load scenarios end to end.
## summary

- Pass a resolveStageAssetSource callback from the workspace into the
  director stage, so a model whose document pins an asset but carries no
  live preview URL (stage JSON import, reopened project) loads its bytes
  through the open project instead of staying a permanent placeholder.
- Report the existing assetState field on director nodes from the
  projection: "missing" when the pinned still or any model asset cannot
  be read, "ready" otherwise. The stage shows a bilingual notice for the
  missing state instead of an unexplained empty scene.
- Deliver the new editors.stage.ui.assetsMissing message in zh-CN and
  en-US together.

## validation

- node --test tests/directorStageAssets.test.ts
  tests/creationClient.test.ts tests/creationEditorSession.test.ts
  tests/mediaPublication.test.ts
- npm run check:i18n
- npx tsc --noEmit
## summary

- Record each material's authored emissive color and intensity once per
  asset load, before any runtime state can overwrite it. SkeletonUtils
  clones share materials with the cached scene, so the record covers the
  pristine scene and every clone derived from it.
- Selection highlighting now tints with the highlight color at intensity
  one while selected and restores the authored emissive when deselected,
  instead of destroying it with black on the first pass.
- The MP4 export's private material clones restore the authored emissive
  rather than zeroing it, so emissive surfaces and emissive-only geometry
  survive captured stills and rendered video.

## validation

- npx tsc --noEmit
- node --test tests/canvasStage.test.ts tests/stagePreviewVideoTools.test.ts
- No unit test for the material handling: DirectorStage.tsx is JSX the
  node test runner cannot import; browser lane verifies emissive pixels
  across select, deselect, still and MP4 end to end.
## summary

- Mount the existing non-connectable proxy handles on external
  director-stage nodes for both directions. The publication edge and the
  stage's assembly-input edges need matching handles, and a node with no
  handle at all blocks every React Flow edge touching it, not only the
  published stage's post_edit_result edge.
- nodePorts stays the interactive connection policy: external nodes
  still cannot start or receive interactive generation references; the
  restored handles only let existing projection edges render.

## validation

- npx tsc --noEmit
- node --test tests/canvasCapabilities.test.ts tests/canvasInteraction.test.ts
  tests/nodeReferencePorts.test.ts
- No component unit test exists for NodeFrame; the browser lane asserts
  the published stage's edge element renders.
## summary

- Record each still imported from a director node's transient
  stillCapture, and remove the spent capture from the saved document
  after the batch commits. The saved document aliases the caller's live
  snapshot, so the field cannot survive into a later session and
  register a duplicate image asset under fresh:true.
- Match the clear by node id and exact capture value, so a newer
  capture applied while the save was in flight stays untouched, and a
  failed save keeps the capture for its retry.
- The MP4 publication path's fresh import is untouched: each render is
  genuinely new bytes, unlike a capture pinned by an acknowledged save.

## validation

- node --test tests/directorStageAssets.test.ts
- npx tsc --noEmit
## summary

- Trim the doubled trailing newline the pre-commit end-of-file-fixer
  flags on seven files the stacked branch diff touches.

## validation

- python -m pre_commit run --from-ref origin/main --to-ref HEAD
## summary

- Add director_stage_media_travel.mjs: authored emissive survives
  selection into a captured still (pixel-probed), stage JSON round trips
  resolve pinned assets, a delayed model holds the render while a failed
  fetch refuses it without publishing, cross-project paste re-homes the
  still and model pins, a canvas archive round trip carries stage media,
  and the published stage's provenance edge renders.
- Extend director_stage_output.mjs with a reload-and-apply assertion that
  a fresh session registers no duplicate still, and report renderMs for
  perf probes.
- Add makeEmissiveGlb to the stage GLB fixture and register the new
  script in the manual browser lane.

## validation

- Isolated creation server + Vite; the new script passed at this head
  (8 checks, screenshots under /tmp/pr330) and fails at 8733eef with the
  emissive probe reading 0, reproducing the review finding on the
  baseline.
- director_stage_entry.mjs (en-US and zh-CN), director_stage_animation,
  director_stage_delivery, director_stage_output all passed at this head.
- npm run check:browser-manifest, npm run check:browser-locale.
@github-actions github-actions Bot added area:agent Agent runtime, assistant chat and tools area:timeline Timeline, subtitles and export labels Nov 17, 2026
@MrDongsls

Copy link
Copy Markdown
Contributor Author

Thanks for the review — all six Codex findings and both additional points are addressed in 3602caf..dba5d99 (pushed to this branch).

On your two points:

  1. Silent swallows. e4155d3 replaces the two mediaUrl(...).catch(() => undefined) sites with an explicit assetState of ready/missing on the director node (reusing the existing CanvasNodeData.assetState field) plus a bilingual editors.stage.ui.assetsMissing notice in the stage, and the same commit resolves pinned models without a preview URL through a new resolveStageAssetSource callback instead of leaving a permanent placeholder. The import path and the projection rebuild path now both surface or resolve, respectively.

  2. fresh: true on every save. The duplicate was real: stillCapture was never cleared anywhere, so a fresh session's first save re-registered the same PNG. 6729e9e clears the capture after the save that imported it commits (value-matched, so a newer capture landing mid-save survives and a failed save keeps its capture for the retry). fresh: true itself stays: the MP4 publication path shares the flag and each render is genuinely new bytes, unlike a capture already pinned by an acknowledged save. A full projection.save unit case covers the cross-session no-duplicate behavior, and director_stage_output.mjs now also asserts that reopening and applying registers no second still.

Validation at dba5d99: npm test (847), pytest (2024 passed, 100 skipped), npm run build, check:i18n, check:browser-manifest, check:browser-locale, contracts check, and the pre-commit range check all pass. Browser coverage at the new head: director_stage_entry (en-US and zh-CN), director_stage_animation, director_stage_delivery, director_stage_output, and the new director_stage_media_travel lane (emissive pixel probe, stage JSON round trip, delayed and failing model renders, cross-project paste, archive round trip, published-edge rendering; screenshots available). The travel script was also run against 8733eef, where the emissive probe reads 0 — the baseline reproduces the finding the head fixes. Render timing probe, three interleaved runs per side: median 1967 ms at 8733eef vs 2367 ms at the head, well inside the 20 s budget.

One known gap, recorded honestly: the missing-still notice is verified at the unit and i18n level; the isolated creation server has no fixture to make a pinned asset's bytes unreadable, so the notice's browser-level rendering is not yet exercised end to end.

@MrDongsls
MrDongsls marked this pull request as draft November 17, 2026 14:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:agent Agent runtime, assistant chat and tools area:docs Documentation / 文档 area:timeline Timeline, subtitles and export

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants