From 7a3e5ff0f31e3e4255b9cc233f7f56b7548534cc Mon Sep 17 00:00:00 2001 From: Etienne Lescot Date: Sun, 26 Jul 2026 17:46:48 +0200 Subject: [PATCH 01/17] docs: rename docs/ to technical-documentation/ and stage the reorg skeleton git mv only: surviving docs land on their target names so history follows, everything that is migration/merge/POC narrative moves to _harvest/ to be harvested and deleted. Adds scripts/check-docs.mjs as the gate. --- scripts/check-docs.mjs | 118 ++++++++++++++++++ technical-documentation/_harvest/_BRIEF.md | 80 ++++++++++++ .../ai-edition-collision-analysis.md | 0 .../_harvest}/ai-edition-remediation-spec.md | 0 .../_harvest}/ai-edition-roadmap.md | 0 .../_harvest}/axcut-inventory.md | 0 .../_harvest}/axcut-ux-ui-spec.md | 0 .../_harvest}/macos-native-cursor.md | 0 .../macos-native-recorder-roadmap.md | 0 .../_harvest}/main-vs-ai-edition-audit.md | 0 .../_harvest}/openscreen-inventory.md | 0 .../_harvest}/openscreen-ux-ui-spec.md | 0 .../_harvest/poc-d3d-HANDOFF.md | 0 .../_harvest/poc-d3d-stages}/S0-frameworks.md | 0 .../_harvest/poc-d3d-stages}/S1-sources.md | 0 .../_harvest/poc-d3d-stages}/S2-c0.md | 0 .../_harvest/poc-d3d-stages}/S6-report.md | 0 .../poc-d3d-stages}/S7-preview-export.md | 0 .../S8-electron-integration.md | 0 .../_harvest/poc-d3d-stages}/d3d-migration.md | 0 .../_harvest/specs}/README.md | 0 .../specs}/computer-use/00-launch-and-hud.md | 0 .../01-source-selection-and-record.md | 0 .../computer-use/02-editor-foundation.md | 0 .../computer-use/03-transport-and-preview.md | 0 .../04-timeline-pan-zoom-scrub.md | 0 .../specs}/computer-use/05-clip-operations.md | 0 .../specs}/computer-use/06-skip-regions.md | 0 .../specs}/computer-use/07-zoom-regions.md | 0 .../specs}/computer-use/08-speed-regions.md | 0 .../computer-use/09-annotation-regions.md | 0 .../computer-use/10-properties-right-panel.md | 0 .../computer-use/11-transcript-editor.md | 0 .../specs}/computer-use/12-chat-panel.md | 0 .../computer-use/13-provider-settings.md | 0 .../computer-use/14-sessions-and-history.md | 0 .../specs}/computer-use/15-export-dialog.md | 0 .../computer-use/16-modal-shortcuts-i18n.md | 0 .../computer-use/17-themes-and-settings.md | 0 .../computer-use/18-final-qa-checklist.md | 0 .../_harvest/specs}/computer-use/INDEX.md | 0 .../f2.6-region-snap-guide-and-tooltip.md | 0 .../specs}/f2.7-multi-select-regions.md | 0 .../specs}/p1.7-chat-tool-call-summaries.md | 0 .../_harvest/specs}/p3.1-asset-file-size.md | 0 .../_harvest/specs}/p3.3-right-panes-help.md | 0 .../_harvest/specs}/p3.7-ruler-hover-scrub.md | 0 .../specs}/t19-zoom-timeline-and-preview.md | 0 .../_harvest}/stt-whispercpp-dtw-poc-plan.md | 0 .../stt-whispercpp-migration-plan.md | 0 .../_harvest}/v4-design-parity.md | 0 .../architecture/cursor.md | 0 .../architecture/export-pipeline.md | 0 .../architecture/llm-providers.md | 0 .../architecture/native-bridge.md | 0 .../architecture/overview.md | 0 .../architecture/recording.md | 0 .../architecture/timeline-model.md | 0 .../transcription-and-captions.md | 0 .../engineering/ci-workflows.md | 0 .../engineering/release-and-secrets.md | 0 .../engineering/rendering-performance.md | 0 .../testing/manual-e2e-checklist.md | 0 .../testing/native-cursor-diagnostics.md | 0 .../testing}/writing-tests.md | 0 65 files changed, 198 insertions(+) create mode 100644 scripts/check-docs.mjs create mode 100644 technical-documentation/_harvest/_BRIEF.md rename {docs/architecture => technical-documentation/_harvest}/ai-edition-collision-analysis.md (100%) rename {docs/engineering => technical-documentation/_harvest}/ai-edition-remediation-spec.md (100%) rename {docs/architecture => technical-documentation/_harvest}/ai-edition-roadmap.md (100%) rename {docs/architecture => technical-documentation/_harvest}/axcut-inventory.md (100%) rename {docs => technical-documentation/_harvest}/axcut-ux-ui-spec.md (100%) rename {docs/testing => technical-documentation/_harvest}/macos-native-cursor.md (100%) rename {docs/engineering => technical-documentation/_harvest}/macos-native-recorder-roadmap.md (100%) rename {docs/engineering => technical-documentation/_harvest}/main-vs-ai-edition-audit.md (100%) rename {docs/architecture => technical-documentation/_harvest}/openscreen-inventory.md (100%) rename {docs => technical-documentation/_harvest}/openscreen-ux-ui-spec.md (100%) rename poc-d3d/HANDOFF.md => technical-documentation/_harvest/poc-d3d-HANDOFF.md (100%) rename {poc-d3d/docs => technical-documentation/_harvest/poc-d3d-stages}/S0-frameworks.md (100%) rename {poc-d3d/docs => technical-documentation/_harvest/poc-d3d-stages}/S1-sources.md (100%) rename {poc-d3d/docs => technical-documentation/_harvest/poc-d3d-stages}/S2-c0.md (100%) rename {poc-d3d/docs => technical-documentation/_harvest/poc-d3d-stages}/S6-report.md (100%) rename {poc-d3d/docs => technical-documentation/_harvest/poc-d3d-stages}/S7-preview-export.md (100%) rename {poc-d3d/docs => technical-documentation/_harvest/poc-d3d-stages}/S8-electron-integration.md (100%) rename {poc-d3d/docs => technical-documentation/_harvest/poc-d3d-stages}/d3d-migration.md (100%) rename {specs => technical-documentation/_harvest/specs}/README.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/00-launch-and-hud.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/01-source-selection-and-record.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/02-editor-foundation.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/03-transport-and-preview.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/04-timeline-pan-zoom-scrub.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/05-clip-operations.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/06-skip-regions.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/07-zoom-regions.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/08-speed-regions.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/09-annotation-regions.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/10-properties-right-panel.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/11-transcript-editor.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/12-chat-panel.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/13-provider-settings.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/14-sessions-and-history.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/15-export-dialog.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/16-modal-shortcuts-i18n.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/17-themes-and-settings.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/18-final-qa-checklist.md (100%) rename {specs => technical-documentation/_harvest/specs}/computer-use/INDEX.md (100%) rename {specs => technical-documentation/_harvest/specs}/f2.6-region-snap-guide-and-tooltip.md (100%) rename {specs => technical-documentation/_harvest/specs}/f2.7-multi-select-regions.md (100%) rename {specs => technical-documentation/_harvest/specs}/p1.7-chat-tool-call-summaries.md (100%) rename {specs => technical-documentation/_harvest/specs}/p3.1-asset-file-size.md (100%) rename {specs => technical-documentation/_harvest/specs}/p3.3-right-panes-help.md (100%) rename {specs => technical-documentation/_harvest/specs}/p3.7-ruler-hover-scrub.md (100%) rename {specs => technical-documentation/_harvest/specs}/t19-zoom-timeline-and-preview.md (100%) rename {docs/engineering => technical-documentation/_harvest}/stt-whispercpp-dtw-poc-plan.md (100%) rename {docs/engineering => technical-documentation/_harvest}/stt-whispercpp-migration-plan.md (100%) rename {docs/ai-edition => technical-documentation/_harvest}/v4-design-parity.md (100%) rename docs/cursor-feature-inventory.md => technical-documentation/architecture/cursor.md (100%) rename {docs => technical-documentation}/architecture/export-pipeline.md (100%) rename docs/provider-parity-plan.md => technical-documentation/architecture/llm-providers.md (100%) rename {docs => technical-documentation}/architecture/native-bridge.md (100%) rename docs/architecture/ai-edition-data-flow.md => technical-documentation/architecture/overview.md (100%) rename docs/engineering/windows-native-recorder-roadmap.md => technical-documentation/architecture/recording.md (100%) rename docs/architecture/timeline-coordinate-refactor.md => technical-documentation/architecture/timeline-model.md (100%) rename docs/engineering/stt-spec.md => technical-documentation/architecture/transcription-and-captions.md (100%) rename docs/github-actions-workflows.md => technical-documentation/engineering/ci-workflows.md (100%) rename docs/secrets.md => technical-documentation/engineering/release-and-secrets.md (100%) rename docs/architecture/rendering-architecture.md => technical-documentation/engineering/rendering-performance.md (100%) rename docs/testing/rc-e2e-checklist.md => technical-documentation/testing/manual-e2e-checklist.md (100%) rename docs/testing/windows-native-cursor.md => technical-documentation/testing/native-cursor-diagnostics.md (100%) rename {docs/tests => technical-documentation/testing}/writing-tests.md (100%) diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs new file mode 100644 index 000000000..2a5cbadf0 --- /dev/null +++ b/scripts/check-docs.mjs @@ -0,0 +1,118 @@ +#!/usr/bin/env node +// Docs lint for technical-documentation/: relative links resolve, no legacy +// identifiers are presented as current, and every expected file is real. +// ponytail: three regex passes over ~30 files, no deps. Run: node scripts/check-docs.mjs +import { readdirSync, readFileSync, statSync } from "node:fs"; +import { dirname, join, relative, resolve } from "node:path"; + +const ROOT = resolve(import.meta.dirname, ".."); +const DOCS = join(ROOT, "technical-documentation"); + +// Names of components / docs that no longer exist on this branch. A doc may only +// mention them inside a "removed / superseded" note, which lives in decisions.md. +const LEGACY = [ + "TimelinePane", + "RightPanelStack", + "Bottombar", + "Titlebar", + "TranscriptEditor", + "ai-edition-roadmap", + "ai-edition-collision-analysis", + "openscreen-inventory", + "axcut-inventory", + "main-vs-ai-edition", + "ai-edition-remediation", + "v4-design-parity", + "stt-whispercpp-migration-plan", + "stt-whispercpp-dtw-poc-plan", + "rendering-architecture.md", + "timeline-coordinate-refactor", + "cursor-feature-inventory", + "provider-parity-plan", + "github-actions-workflows", + "ux-ui-spec", +]; +const LEGACY_ALLOWED = new Set(["architecture/decisions.md"]); + +const REQUIRED = [ + "README.md", + "architecture/overview.md", + "architecture/document-model.md", + "architecture/timeline-model.md", + "architecture/editor-shell.md", + "architecture/preview.md", + "architecture/native-compositor.md", + "architecture/export-pipeline.md", + "architecture/recording.md", + "architecture/native-bridge.md", + "architecture/transcription-and-captions.md", + "architecture/ai-agent.md", + "architecture/llm-providers.md", + "architecture/cursor.md", + "architecture/decisions.md", + "engineering/rendering-performance.md", + "engineering/build-and-packaging.md", + "engineering/ci-workflows.md", + "engineering/release-and-secrets.md", + "testing/writing-tests.md", + "testing/manual-e2e-checklist.md", + "testing/native-cursor-diagnostics.md", +]; + +function walk(dir) { + const out = []; + for (const entry of readdirSync(dir, { withFileTypes: true })) { + if (entry.name === "_harvest") continue; + const full = join(dir, entry.name); + if (entry.isDirectory()) out.push(...walk(full)); + else if (entry.name.endsWith(".md")) out.push(full); + } + return out; +} + +const errors = []; +const files = walk(DOCS); + +for (const abs of REQUIRED) { + const full = join(DOCS, abs); + let lines = -1; + try { + lines = readFileSync(full, "utf8").split("\n").length; + } catch { + errors.push(`missing: technical-documentation/${abs}`); + continue; + } + if (lines < 30) errors.push(`stub (${lines} lines): technical-documentation/${abs}`); +} + +for (const file of files) { + const rel = relative(DOCS, file).replaceAll("\\", "/"); + const text = readFileSync(file, "utf8"); + + // Relative markdown links must resolve. + for (const [, target] of text.matchAll(/\]\((?!https?:|mailto:|#)([^)#\s]+)/g)) { + const resolved = resolve(dirname(file), target); + try { + statSync(resolved); + } catch { + errors.push(`${rel}: broken link → ${target}`); + } + } + + // No stale `docs/` path prefix. + for (const [match] of text.matchAll(/(?Edits / Modifiers level
zooms, speeds, trims, …"] + T["Timeline level
clip order (1, 2, …)"] + C["Clip level
attached media: screen · camera · mic · system audio
crop + in/out timestamps"] + end + DSL[["DSL — AxcutDocument
single source of truth"]] + P["Preview"] + R["Render / Export"] + + M -- "authored above the timeline,
stored down on the clip" --> C + T --> DSL + C --> DSL + DSL --> P + DSL --> R +``` + +The gloss must make the load-bearing point explicit: **modifiers are presented above the timeline +in the UX but stored down on the clip in the data**, which is exactly the invariant +`architecture/timeline-model.md` exists to protect. diff --git a/docs/architecture/ai-edition-collision-analysis.md b/technical-documentation/_harvest/ai-edition-collision-analysis.md similarity index 100% rename from docs/architecture/ai-edition-collision-analysis.md rename to technical-documentation/_harvest/ai-edition-collision-analysis.md diff --git a/docs/engineering/ai-edition-remediation-spec.md b/technical-documentation/_harvest/ai-edition-remediation-spec.md similarity index 100% rename from docs/engineering/ai-edition-remediation-spec.md rename to technical-documentation/_harvest/ai-edition-remediation-spec.md diff --git a/docs/architecture/ai-edition-roadmap.md b/technical-documentation/_harvest/ai-edition-roadmap.md similarity index 100% rename from docs/architecture/ai-edition-roadmap.md rename to technical-documentation/_harvest/ai-edition-roadmap.md diff --git a/docs/architecture/axcut-inventory.md b/technical-documentation/_harvest/axcut-inventory.md similarity index 100% rename from docs/architecture/axcut-inventory.md rename to technical-documentation/_harvest/axcut-inventory.md diff --git a/docs/axcut-ux-ui-spec.md b/technical-documentation/_harvest/axcut-ux-ui-spec.md similarity index 100% rename from docs/axcut-ux-ui-spec.md rename to technical-documentation/_harvest/axcut-ux-ui-spec.md diff --git a/docs/testing/macos-native-cursor.md b/technical-documentation/_harvest/macos-native-cursor.md similarity index 100% rename from docs/testing/macos-native-cursor.md rename to technical-documentation/_harvest/macos-native-cursor.md diff --git a/docs/engineering/macos-native-recorder-roadmap.md b/technical-documentation/_harvest/macos-native-recorder-roadmap.md similarity index 100% rename from docs/engineering/macos-native-recorder-roadmap.md rename to technical-documentation/_harvest/macos-native-recorder-roadmap.md diff --git a/docs/engineering/main-vs-ai-edition-audit.md b/technical-documentation/_harvest/main-vs-ai-edition-audit.md similarity index 100% rename from docs/engineering/main-vs-ai-edition-audit.md rename to technical-documentation/_harvest/main-vs-ai-edition-audit.md diff --git a/docs/architecture/openscreen-inventory.md b/technical-documentation/_harvest/openscreen-inventory.md similarity index 100% rename from docs/architecture/openscreen-inventory.md rename to technical-documentation/_harvest/openscreen-inventory.md diff --git a/docs/openscreen-ux-ui-spec.md b/technical-documentation/_harvest/openscreen-ux-ui-spec.md similarity index 100% rename from docs/openscreen-ux-ui-spec.md rename to technical-documentation/_harvest/openscreen-ux-ui-spec.md diff --git a/poc-d3d/HANDOFF.md b/technical-documentation/_harvest/poc-d3d-HANDOFF.md similarity index 100% rename from poc-d3d/HANDOFF.md rename to technical-documentation/_harvest/poc-d3d-HANDOFF.md diff --git a/poc-d3d/docs/S0-frameworks.md b/technical-documentation/_harvest/poc-d3d-stages/S0-frameworks.md similarity index 100% rename from poc-d3d/docs/S0-frameworks.md rename to technical-documentation/_harvest/poc-d3d-stages/S0-frameworks.md diff --git a/poc-d3d/docs/S1-sources.md b/technical-documentation/_harvest/poc-d3d-stages/S1-sources.md similarity index 100% rename from poc-d3d/docs/S1-sources.md rename to technical-documentation/_harvest/poc-d3d-stages/S1-sources.md diff --git a/poc-d3d/docs/S2-c0.md b/technical-documentation/_harvest/poc-d3d-stages/S2-c0.md similarity index 100% rename from poc-d3d/docs/S2-c0.md rename to technical-documentation/_harvest/poc-d3d-stages/S2-c0.md diff --git a/poc-d3d/docs/S6-report.md b/technical-documentation/_harvest/poc-d3d-stages/S6-report.md similarity index 100% rename from poc-d3d/docs/S6-report.md rename to technical-documentation/_harvest/poc-d3d-stages/S6-report.md diff --git a/poc-d3d/docs/S7-preview-export.md b/technical-documentation/_harvest/poc-d3d-stages/S7-preview-export.md similarity index 100% rename from poc-d3d/docs/S7-preview-export.md rename to technical-documentation/_harvest/poc-d3d-stages/S7-preview-export.md diff --git a/poc-d3d/docs/S8-electron-integration.md b/technical-documentation/_harvest/poc-d3d-stages/S8-electron-integration.md similarity index 100% rename from poc-d3d/docs/S8-electron-integration.md rename to technical-documentation/_harvest/poc-d3d-stages/S8-electron-integration.md diff --git a/poc-d3d/docs/d3d-migration.md b/technical-documentation/_harvest/poc-d3d-stages/d3d-migration.md similarity index 100% rename from poc-d3d/docs/d3d-migration.md rename to technical-documentation/_harvest/poc-d3d-stages/d3d-migration.md diff --git a/specs/README.md b/technical-documentation/_harvest/specs/README.md similarity index 100% rename from specs/README.md rename to technical-documentation/_harvest/specs/README.md diff --git a/specs/computer-use/00-launch-and-hud.md b/technical-documentation/_harvest/specs/computer-use/00-launch-and-hud.md similarity index 100% rename from specs/computer-use/00-launch-and-hud.md rename to technical-documentation/_harvest/specs/computer-use/00-launch-and-hud.md diff --git a/specs/computer-use/01-source-selection-and-record.md b/technical-documentation/_harvest/specs/computer-use/01-source-selection-and-record.md similarity index 100% rename from specs/computer-use/01-source-selection-and-record.md rename to technical-documentation/_harvest/specs/computer-use/01-source-selection-and-record.md diff --git a/specs/computer-use/02-editor-foundation.md b/technical-documentation/_harvest/specs/computer-use/02-editor-foundation.md similarity index 100% rename from specs/computer-use/02-editor-foundation.md rename to technical-documentation/_harvest/specs/computer-use/02-editor-foundation.md diff --git a/specs/computer-use/03-transport-and-preview.md b/technical-documentation/_harvest/specs/computer-use/03-transport-and-preview.md similarity index 100% rename from specs/computer-use/03-transport-and-preview.md rename to technical-documentation/_harvest/specs/computer-use/03-transport-and-preview.md diff --git a/specs/computer-use/04-timeline-pan-zoom-scrub.md b/technical-documentation/_harvest/specs/computer-use/04-timeline-pan-zoom-scrub.md similarity index 100% rename from specs/computer-use/04-timeline-pan-zoom-scrub.md rename to technical-documentation/_harvest/specs/computer-use/04-timeline-pan-zoom-scrub.md diff --git a/specs/computer-use/05-clip-operations.md b/technical-documentation/_harvest/specs/computer-use/05-clip-operations.md similarity index 100% rename from specs/computer-use/05-clip-operations.md rename to technical-documentation/_harvest/specs/computer-use/05-clip-operations.md diff --git a/specs/computer-use/06-skip-regions.md b/technical-documentation/_harvest/specs/computer-use/06-skip-regions.md similarity index 100% rename from specs/computer-use/06-skip-regions.md rename to technical-documentation/_harvest/specs/computer-use/06-skip-regions.md diff --git a/specs/computer-use/07-zoom-regions.md b/technical-documentation/_harvest/specs/computer-use/07-zoom-regions.md similarity index 100% rename from specs/computer-use/07-zoom-regions.md rename to technical-documentation/_harvest/specs/computer-use/07-zoom-regions.md diff --git a/specs/computer-use/08-speed-regions.md b/technical-documentation/_harvest/specs/computer-use/08-speed-regions.md similarity index 100% rename from specs/computer-use/08-speed-regions.md rename to technical-documentation/_harvest/specs/computer-use/08-speed-regions.md diff --git a/specs/computer-use/09-annotation-regions.md b/technical-documentation/_harvest/specs/computer-use/09-annotation-regions.md similarity index 100% rename from specs/computer-use/09-annotation-regions.md rename to technical-documentation/_harvest/specs/computer-use/09-annotation-regions.md diff --git a/specs/computer-use/10-properties-right-panel.md b/technical-documentation/_harvest/specs/computer-use/10-properties-right-panel.md similarity index 100% rename from specs/computer-use/10-properties-right-panel.md rename to technical-documentation/_harvest/specs/computer-use/10-properties-right-panel.md diff --git a/specs/computer-use/11-transcript-editor.md b/technical-documentation/_harvest/specs/computer-use/11-transcript-editor.md similarity index 100% rename from specs/computer-use/11-transcript-editor.md rename to technical-documentation/_harvest/specs/computer-use/11-transcript-editor.md diff --git a/specs/computer-use/12-chat-panel.md b/technical-documentation/_harvest/specs/computer-use/12-chat-panel.md similarity index 100% rename from specs/computer-use/12-chat-panel.md rename to technical-documentation/_harvest/specs/computer-use/12-chat-panel.md diff --git a/specs/computer-use/13-provider-settings.md b/technical-documentation/_harvest/specs/computer-use/13-provider-settings.md similarity index 100% rename from specs/computer-use/13-provider-settings.md rename to technical-documentation/_harvest/specs/computer-use/13-provider-settings.md diff --git a/specs/computer-use/14-sessions-and-history.md b/technical-documentation/_harvest/specs/computer-use/14-sessions-and-history.md similarity index 100% rename from specs/computer-use/14-sessions-and-history.md rename to technical-documentation/_harvest/specs/computer-use/14-sessions-and-history.md diff --git a/specs/computer-use/15-export-dialog.md b/technical-documentation/_harvest/specs/computer-use/15-export-dialog.md similarity index 100% rename from specs/computer-use/15-export-dialog.md rename to technical-documentation/_harvest/specs/computer-use/15-export-dialog.md diff --git a/specs/computer-use/16-modal-shortcuts-i18n.md b/technical-documentation/_harvest/specs/computer-use/16-modal-shortcuts-i18n.md similarity index 100% rename from specs/computer-use/16-modal-shortcuts-i18n.md rename to technical-documentation/_harvest/specs/computer-use/16-modal-shortcuts-i18n.md diff --git a/specs/computer-use/17-themes-and-settings.md b/technical-documentation/_harvest/specs/computer-use/17-themes-and-settings.md similarity index 100% rename from specs/computer-use/17-themes-and-settings.md rename to technical-documentation/_harvest/specs/computer-use/17-themes-and-settings.md diff --git a/specs/computer-use/18-final-qa-checklist.md b/technical-documentation/_harvest/specs/computer-use/18-final-qa-checklist.md similarity index 100% rename from specs/computer-use/18-final-qa-checklist.md rename to technical-documentation/_harvest/specs/computer-use/18-final-qa-checklist.md diff --git a/specs/computer-use/INDEX.md b/technical-documentation/_harvest/specs/computer-use/INDEX.md similarity index 100% rename from specs/computer-use/INDEX.md rename to technical-documentation/_harvest/specs/computer-use/INDEX.md diff --git a/specs/f2.6-region-snap-guide-and-tooltip.md b/technical-documentation/_harvest/specs/f2.6-region-snap-guide-and-tooltip.md similarity index 100% rename from specs/f2.6-region-snap-guide-and-tooltip.md rename to technical-documentation/_harvest/specs/f2.6-region-snap-guide-and-tooltip.md diff --git a/specs/f2.7-multi-select-regions.md b/technical-documentation/_harvest/specs/f2.7-multi-select-regions.md similarity index 100% rename from specs/f2.7-multi-select-regions.md rename to technical-documentation/_harvest/specs/f2.7-multi-select-regions.md diff --git a/specs/p1.7-chat-tool-call-summaries.md b/technical-documentation/_harvest/specs/p1.7-chat-tool-call-summaries.md similarity index 100% rename from specs/p1.7-chat-tool-call-summaries.md rename to technical-documentation/_harvest/specs/p1.7-chat-tool-call-summaries.md diff --git a/specs/p3.1-asset-file-size.md b/technical-documentation/_harvest/specs/p3.1-asset-file-size.md similarity index 100% rename from specs/p3.1-asset-file-size.md rename to technical-documentation/_harvest/specs/p3.1-asset-file-size.md diff --git a/specs/p3.3-right-panes-help.md b/technical-documentation/_harvest/specs/p3.3-right-panes-help.md similarity index 100% rename from specs/p3.3-right-panes-help.md rename to technical-documentation/_harvest/specs/p3.3-right-panes-help.md diff --git a/specs/p3.7-ruler-hover-scrub.md b/technical-documentation/_harvest/specs/p3.7-ruler-hover-scrub.md similarity index 100% rename from specs/p3.7-ruler-hover-scrub.md rename to technical-documentation/_harvest/specs/p3.7-ruler-hover-scrub.md diff --git a/specs/t19-zoom-timeline-and-preview.md b/technical-documentation/_harvest/specs/t19-zoom-timeline-and-preview.md similarity index 100% rename from specs/t19-zoom-timeline-and-preview.md rename to technical-documentation/_harvest/specs/t19-zoom-timeline-and-preview.md diff --git a/docs/engineering/stt-whispercpp-dtw-poc-plan.md b/technical-documentation/_harvest/stt-whispercpp-dtw-poc-plan.md similarity index 100% rename from docs/engineering/stt-whispercpp-dtw-poc-plan.md rename to technical-documentation/_harvest/stt-whispercpp-dtw-poc-plan.md diff --git a/docs/engineering/stt-whispercpp-migration-plan.md b/technical-documentation/_harvest/stt-whispercpp-migration-plan.md similarity index 100% rename from docs/engineering/stt-whispercpp-migration-plan.md rename to technical-documentation/_harvest/stt-whispercpp-migration-plan.md diff --git a/docs/ai-edition/v4-design-parity.md b/technical-documentation/_harvest/v4-design-parity.md similarity index 100% rename from docs/ai-edition/v4-design-parity.md rename to technical-documentation/_harvest/v4-design-parity.md diff --git a/docs/cursor-feature-inventory.md b/technical-documentation/architecture/cursor.md similarity index 100% rename from docs/cursor-feature-inventory.md rename to technical-documentation/architecture/cursor.md diff --git a/docs/architecture/export-pipeline.md b/technical-documentation/architecture/export-pipeline.md similarity index 100% rename from docs/architecture/export-pipeline.md rename to technical-documentation/architecture/export-pipeline.md diff --git a/docs/provider-parity-plan.md b/technical-documentation/architecture/llm-providers.md similarity index 100% rename from docs/provider-parity-plan.md rename to technical-documentation/architecture/llm-providers.md diff --git a/docs/architecture/native-bridge.md b/technical-documentation/architecture/native-bridge.md similarity index 100% rename from docs/architecture/native-bridge.md rename to technical-documentation/architecture/native-bridge.md diff --git a/docs/architecture/ai-edition-data-flow.md b/technical-documentation/architecture/overview.md similarity index 100% rename from docs/architecture/ai-edition-data-flow.md rename to technical-documentation/architecture/overview.md diff --git a/docs/engineering/windows-native-recorder-roadmap.md b/technical-documentation/architecture/recording.md similarity index 100% rename from docs/engineering/windows-native-recorder-roadmap.md rename to technical-documentation/architecture/recording.md diff --git a/docs/architecture/timeline-coordinate-refactor.md b/technical-documentation/architecture/timeline-model.md similarity index 100% rename from docs/architecture/timeline-coordinate-refactor.md rename to technical-documentation/architecture/timeline-model.md diff --git a/docs/engineering/stt-spec.md b/technical-documentation/architecture/transcription-and-captions.md similarity index 100% rename from docs/engineering/stt-spec.md rename to technical-documentation/architecture/transcription-and-captions.md diff --git a/docs/github-actions-workflows.md b/technical-documentation/engineering/ci-workflows.md similarity index 100% rename from docs/github-actions-workflows.md rename to technical-documentation/engineering/ci-workflows.md diff --git a/docs/secrets.md b/technical-documentation/engineering/release-and-secrets.md similarity index 100% rename from docs/secrets.md rename to technical-documentation/engineering/release-and-secrets.md diff --git a/docs/architecture/rendering-architecture.md b/technical-documentation/engineering/rendering-performance.md similarity index 100% rename from docs/architecture/rendering-architecture.md rename to technical-documentation/engineering/rendering-performance.md diff --git a/docs/testing/rc-e2e-checklist.md b/technical-documentation/testing/manual-e2e-checklist.md similarity index 100% rename from docs/testing/rc-e2e-checklist.md rename to technical-documentation/testing/manual-e2e-checklist.md diff --git a/docs/testing/windows-native-cursor.md b/technical-documentation/testing/native-cursor-diagnostics.md similarity index 100% rename from docs/testing/windows-native-cursor.md rename to technical-documentation/testing/native-cursor-diagnostics.md diff --git a/docs/tests/writing-tests.md b/technical-documentation/testing/writing-tests.md similarity index 100% rename from docs/tests/writing-tests.md rename to technical-documentation/testing/writing-tests.md From 19f478459a6b7d88117d83ce0d19e72f8c6ea10f Mon Sep 17 00:00:00 2001 From: Etienne Lescot Date: Sun, 26 Jul 2026 17:48:01 +0200 Subject: [PATCH 02/17] docs: scope check-docs.mjs to a slice with --only --- scripts/check-docs.mjs | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs index 2a5cbadf0..7222b309c 100644 --- a/scripts/check-docs.mjs +++ b/scripts/check-docs.mjs @@ -59,6 +59,12 @@ const REQUIRED = [ "testing/native-cursor-diagnostics.md", ]; +// `--only a.md,b/c.md` limits both checks to those docs-relative paths, so a +// task that owns a slice of the tree can gate on its slice alone. +const onlyArg = process.argv.find((a) => a.startsWith("--only=")); +const only = onlyArg ? new Set(onlyArg.slice("--only=".length).split(",")) : null; +const owned = (rel) => !only || only.has(rel); + function walk(dir) { const out = []; for (const entry of readdirSync(dir, { withFileTypes: true })) { @@ -74,6 +80,7 @@ const errors = []; const files = walk(DOCS); for (const abs of REQUIRED) { + if (!owned(abs)) continue; const full = join(DOCS, abs); let lines = -1; try { @@ -87,6 +94,7 @@ for (const abs of REQUIRED) { for (const file of files) { const rel = relative(DOCS, file).replaceAll("\\", "/"); + if (!owned(rel)) continue; const text = readFileSync(file, "utf8"); // Relative markdown links must resolve. @@ -95,6 +103,9 @@ for (const file of files) { try { statSync(resolved); } catch { + // Scoped runs tolerate links to docs another task still owes. + const pending = relative(DOCS, resolved).replaceAll("\\", "/"); + if (only && REQUIRED.includes(pending)) continue; errors.push(`${rel}: broken link → ${target}`); } } From 50e8c0adfaf3372b4381656782eb7e84ccc91a5c Mon Sep 17 00:00:00 2001 From: Etienne Lescot Date: Sun, 26 Jul 2026 17:58:16 +0200 Subject: [PATCH 03/17] docs: add the doc index and the decision ledger, repoint every inbound reference README.md is the index (by type, then subsystem); decisions.md is the ledger of what is settled and what was measured and rejected, and the one place allowed to name removed surfaces. Also fixes two live errors found on the way: poc-d3d/README told you to fetch a floating ffmpeg master-latest build when .cargo/config.toml pins n8.1.2 (a mismatch makes the addon's require() fail), and drops a stale worktree handoff that was tracked in .worktrees/. --- .github/workflows/build.yml | 4 +- .gitignore | 2 +- .harness/docs/architecture-overview.md | 2 +- .harness/docs/git-workflow.md | 2 +- .harness/reins/openscreen-dev/agent.md | 2 +- .harness/reins/openscreen-tester/agent.md | 2 +- .worktrees/wt-9ce78f24/HANDOFF.md | 299 ------------------ AGENTS.md | 4 +- electron/media/ffmpegExportIpc.ts | 2 +- electron/native/README.md | 4 +- electron/stt/index.ts | 2 +- electron/stt/modelManager.ts | 2 +- electron/stt/transcriptionContract.ts | 2 +- poc-d3d/.gitignore | 2 +- poc-d3d/README.md | 24 +- scripts/build-whisper-stt.sh | 2 +- scripts/fetch-ffmpeg.mjs | 5 +- src/components/ai-edition/PreviewCanvas.tsx | 2 +- src/components/video-editor/featureFlags.ts | 2 +- src/lib/ai-edition/document/migrate.ts | 2 +- src/lib/ai-edition/schema/index.test.ts | 2 +- src/lib/ai-edition/schema/index.ts | 8 +- src/lib/ai-edition/store/useTimeline.ts | 2 +- .../ai-edition/timeline/timelineMap.test.ts | 2 +- src/lib/ai-edition/timeline/timelineMap.ts | 4 +- src/lib/captioning/transcribe.ts | 2 +- src/lib/exporter/frameRenderer.ts | 2 +- src/lib/exporter/videoExporter.ts | 4 +- src/native/sceneDescription.test.ts | 2 +- technical-documentation/README.md | 64 ++++ .../architecture/decisions.md | 58 ++++ tools/stt-eval/whispercpp-dtw-poc/README.md | 2 +- tools/stt-eval/whispercpp-dtw-poc/REPORT.md | 2 +- 33 files changed, 175 insertions(+), 347 deletions(-) delete mode 100644 .worktrees/wt-9ce78f24/HANDOFF.md create mode 100644 technical-documentation/README.md create mode 100644 technical-documentation/architecture/decisions.md diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 319a9473b..33fba4806 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -46,7 +46,7 @@ jobs: # ponytail: STT is handled by the bundled whisper-stt-server (whisper.cpp # with native DTW token timestamps). No separate VAD model is fetched - # here. See docs/engineering/stt-spec.md for the full architecture. + # here. See technical-documentation/architecture/transcription-and-captions.md for the full architecture. - name: Build Windows app run: npm run build:win -- --publish never @@ -77,7 +77,7 @@ jobs: # ponytail: STT is handled by the bundled whisper-stt-server (whisper.cpp # with native DTW token timestamps). No separate VAD model is fetched - # here. See docs/engineering/stt-spec.md for the full architecture. + # here. See technical-documentation/architecture/transcription-and-captions.md for the full architecture. - name: Build Windows Store package run: npm run build:win:store -- --publish never diff --git a/.gitignore b/.gitignore index ccc431231..82bb66e0d 100644 --- a/.gitignore +++ b/.gitignore @@ -84,7 +84,7 @@ result-* # whisper.cpp DTW POC (tools/stt-eval/whispercpp-dtw-poc) — vendored engine # clone, downloaded GGML models, and generated build/results artifacts. -# See docs/engineering/stt-whispercpp-dtw-poc-plan.md. +# See technical-documentation/architecture/transcription-and-captions.md. /tools/stt-eval/whispercpp-dtw-poc/whisper.cpp/ /tools/stt-eval/whispercpp-dtw-poc/build-cpu/ /tools/stt-eval/whispercpp-dtw-poc/build-vulkan/ diff --git a/.harness/docs/architecture-overview.md b/.harness/docs/architecture-overview.md index 373f9618e..dbc2e4df5 100644 --- a/.harness/docs/architecture-overview.md +++ b/.harness/docs/architecture-overview.md @@ -1,6 +1,6 @@ # OpenScreen Architecture Notes -Quick map of how the app fits together, for the Mavis reins. For deeper details, see `../docs/architecture/native-bridge.md` and `../docs/engineering/`. +Quick map of how the app fits together, for the Mavis reins. For deeper details, see `../technical-documentation/architecture/native-bridge.md` and `../technical-documentation/engineering/`. ## Process layout diff --git a/.harness/docs/git-workflow.md b/.harness/docs/git-workflow.md index cd0895fdc..68f248645 100644 --- a/.harness/docs/git-workflow.md +++ b/.harness/docs/git-workflow.md @@ -41,7 +41,7 @@ All five must be green before merge. Native helper code is NOT covered by CI — ## Release flow -Two `workflow_dispatch` workflows cut a release. Trunk-based on `main`, but **release branches freeze the RC codebase between cut and promote** (see § Release branches below). Both require the `OPENSCREEN_RELEASE_TOKEN` secret — see `docs/secrets.md`. +Two `workflow_dispatch` workflows cut a release. Trunk-based on `main`, but **release branches freeze the RC codebase between cut and promote** (see § Release branches below). Both require the `OPENSCREEN_RELEASE_TOKEN` secret — see `technical-documentation/engineering/release-and-secrets.md`. ### Step 1: cut a release candidate diff --git a/.harness/reins/openscreen-dev/agent.md b/.harness/reins/openscreen-dev/agent.md index 33c4a28a1..4bd9ce150 100644 --- a/.harness/reins/openscreen-dev/agent.md +++ b/.harness/reins/openscreen-dev/agent.md @@ -15,7 +15,7 @@ You are the generalist implementer for the OpenScreen project — a free, open-s ## How you work - Read `AGENTS.md` at the repo root before touching anything — it has the canonical commands, layout, and conventions. -- When the change touches recording, IPC, or the native bridge, read `.harness/docs/architecture-overview.md` (start here), `docs/architecture/native-bridge.md` (deeper dive), and `docs/engineering/` (native helper roadmaps). +- When the change touches recording, IPC, or the native bridge, read `.harness/docs/architecture-overview.md` (start here), `technical-documentation/architecture/native-bridge.md` (deeper dive), and `technical-documentation/engineering/` (native helper roadmaps). - TypeScript strict mode, Biome format (tabs, double quotes, 100-col). Run `npm run lint:fix` before committing. - For renderer-only iteration use `npm run build-vite`. For full packaging use `npm run build` (electron-builder, slow). - Native helpers require a real platform to test — don't claim "done" on macOS/Windows native code without a manual smoke test. diff --git a/.harness/reins/openscreen-tester/agent.md b/.harness/reins/openscreen-tester/agent.md index cbf3afdc6..bd4658ce4 100644 --- a/.harness/reins/openscreen-tester/agent.md +++ b/.harness/reins/openscreen-tester/agent.md @@ -15,7 +15,7 @@ You are the test specialist for the OpenScreen project — a free, open-source s ## How you work - Read `AGENTS.md` at the repo root for commands and conventions. -- Read `docs/tests/writing-tests.md` for the project's test style guide. +- Read `technical-documentation/testing/writing-tests.md` for the project's test style guide. - Match the style of neighboring `*.test.` files in the same package — don't invent new patterns. - Unit tests: `npm run test` (Vitest, jsdom). Browser tests: `npm run test:browser` (needs `npm run test:browser:install` once). E2E: `npm run test:e2e` (Playwright). - E2E specs in `tests/e2e/windows-native-checklist.spec.ts` are Windows-only — gate with `test.skip` for other platforms rather than deleting. diff --git a/.worktrees/wt-9ce78f24/HANDOFF.md b/.worktrees/wt-9ce78f24/HANDOFF.md deleted file mode 100644 index 9ab72d318..000000000 --- a/.worktrees/wt-9ce78f24/HANDOFF.md +++ /dev/null @@ -1,299 +0,0 @@ -# AI-Edition Implementation Handoff - -**Branch**: `docs/ai-edition-plan` (commit `cf25858`, pushed to `origin`) -**Worktree**: `G:\repos\openscreen\.worktrees\wt-9ce78f24` -**Dev server**: `http://localhost:5173/?windowType=editor` (browser mode with shim) - ---- - -## 1. Context - -The user (Etienne Lescot, repo owner) was working through the implementation of the **OpenScreen x Axcut AI-edition merge**. The original PR #35 (commit `1e9db17` on the same branch) introduced the planning docs only: - -- `docs/architecture/ai-edition-merge-plan.md` — the 10-phase merge plan -- `docs/architecture/axcut-inventory.md` — catalog of the axcut codebase -- `docs/architecture/openscreen-inventory.md` — catalog of the OpenScreen codebase -- `docs/architecture/ai-edition-collision-analysis.md` — collision analysis - -This implementation PR (`cf25858`) delivers the **code** for that plan — all phases 0, 1, 3, 4, 6-8, and partial 9, plus a developer-convenience browser shim and spec updates that changed the framing. - -The plan was re-framed mid-implementation. The user clarified: -- **New editing model** (multi-asset, clips, skips, transcript, virtual-time preview) = **default for all users**, not opt-in -- **AI features** (LLM provider config, chat) = **opt-in** behind `AI_FEATURES_ENABLED` -- **Local Whisper** = **privacy-safe, not gated** (runs in-browser, never calls out) - -This is the spec's `§0 Framing` section. See `docs/architecture/ai-edition-merge-plan.md` lines ~13-65. - ---- - -## 2. What was built (file by file) - -### 2.1 Schema & migration (`src/lib/ai-edition/`) - -| File | Purpose | -|------|---------| -| `schema/index.ts` | Vendored axcut v2 schema + v3 additions (`annotations[]`, `zoomRanges[]`, `legacyEditor` envelope, `transcripts[]`). `axcutSchemaVersion = 3`. `clip.sourceEndSec` made optional (duration unknown at migration time). | -| `schema/index.test.ts` | 15 schema tests (version enforcement, optional clip duration, envelope passthrough, etc.) | -| `document/timeline.ts` | Pure interval math: `normalizeIntervals`, `subtractInterval`, `invertIntervals`, `buildTimelineFromIntervals`, `replaceTimeline`, `restoreFullTimeline`. Ported from axcut `apps/server/src/lib/timeline.ts` (no event bridge, no agent — just the math). | -| `document/timeline.test.ts` | 14 tests covering all the above. | -| `document/migrate.ts` | Bidirectional `EditorProjectData` (v2) ↔ `AxcutDocument` (v3). Notes: `zoomRanges`/`annotations` use **ms** units to mirror the legacy types; timeline ops use **sec** units. The migration is lossless in both directions thanks to the `legacyEditor` passthrough. | -| `document/migrate.test.ts` | 14 tests including round-trip, v1 legacy, focus clamping. | -| `document/transcribe.ts` | `transcribeAsset(document, assetId)` wraps the existing `extractMono16kFromVideoUrl` + `transcribeMono16kToSegments` (from `src/lib/captioning/`). Returns an `AxcutTranscript`. `withTranscript` writes it back to the document. | -| `document/ids.ts` | `createId(prefix)` using `uuid.v4()`. | -| `timeline/virtual-preview.ts` | Pure time-mapping: `totalVirtualDuration`, `clampVirtualTime`, `locateVirtualPosition`, `locateSourcePosition`, `keptWordIdSet`, `formatSeconds`. | -| `timeline/virtual-preview.test.ts` | 8 tests. | -| `store/projectStore.ts` | Zustand store: `projectId`, `document`, `revision`, `status`, `error`, `sourceDurationSec`, `currentTimeSec`. Actions: `loadProject`, `createProject`, `addAsset`, `removeAsset`, `replaceTimeline`, `restoreFullTimeline`, `setTranscript`, `setSourceDuration`, `setCurrentTime`, `saveDocument`, `setDocument`, `clear`. | -| `store/projectStore.test.ts` | 5 tests with `nativeBridgeClient.aiEdition` mocked. | -| `exporter/documentExporter.ts` | Adapter: maps `AxcutDocument` → `VideoExporterConfig` / `GifExporterConfig`. Clips → `trimRegions` (inverse). Reads `legacyEditor` for wallpaper, cursor, webcam, etc. `sourceWidth`/`sourceHeight` come from caller. | - -### 2.2 Main-process services (`electron/ai-edition/`) - -| File | Purpose | -|------|---------| -| `document-service.ts` | `DocumentService(projectsRoot)`: `listProjects`, `getProject(projectId)`, `createProject(title)`, `saveProject(doc)`, `deleteProject(projectId)`, `addAsset(projectId, {path, label?})`, `removeAsset(projectId, assetId)`. One `.axcut` JSON file per project under `app.getPath('userData')/projects/`. Validates paths against an allowlist of video extensions. Cascades clips + skipRanges on asset removal. | -| `document-service.test.ts` | 16 tests (CRUD, path traversal, cascade, primary-asset reassignment). | -| `provider-registry.ts` | 8 provider definitions (anthropic, openai, google, mistral, openrouter, openai-compatible, openai-oauth, copilot-proxy) with `authKind`, `supportsReasoningEffort`, `envKeys`, `baseUrl`. Ported from axcut `provider-registry.ts`. | -| `llm-config-store.ts` | `LlmConfigStore(userDataPath)`: config in `llm-config.json` plain JSON, **credentials in `safeStorage`-encrypted bytes** at `llm-credentials.enc`. Env vars override stored keys (same precedence as axcut). | -| `chat-service.ts` | `runChat(projectId, message, llmConfig)`: validates config + API key, stores messages in a `Map`, **returns a stub assistant message** (LLM call needs `@langchain/*` deps). `getChatHistory(projectId)` returns the in-memory list. | -| `native-bridge/services/aiEditionService.ts` | Adapter to the existing `native-bridge` envelope: wraps `DocumentService`, `LlmConfigStore`, and the chat stubs into the `domain: "aiEdition"` IPC contract. | - -### 2.3 IPC bridge extensions - -- `electron/ipc/nativeBridge.ts` — added the `aiEdition` domain case. Each action calls into `AiEditionService` (`document.listProjects`, `document.get`, `document.create`, `document.save`, `document.delete`, `document.addAsset`, `document.removeAsset`, `llm.getSnapshot`, `llm.setConfig`, `llm.setApiKey`, `llm.removeApiKey`, `chat.run`, `chat.history`). -- `electron/ipc/handlers.ts` — wires `DocumentService` + `LlmConfigStore` + chat functions into the `NativeBridgeContext`. -- `src/native/contracts.ts` — adds `AiEditionLlmConfig`, `AiEditionLlmSnapshot`, `AiEditionChatMessage`, `AiEditionChatResult` types and the new `aiEdition` action cases to the `NativeBridgeRequest` union. -- `src/native/client.ts` — adds the `nativeBridgeClient.aiEdition` namespace with `listProjects`, `get`, `create`, `save`, `delete`, `addAsset`, `removeAsset`, `llmGetSnapshot`, `llmSetConfig`, `llmSetApiKey`, `llmRemoveApiKey`, `chatRun`, `chatHistory`. -- `src/native/browserShim.ts` — **new**. Browser-mode shim that: - - Stubs `window.electronAPI` (no-op `openVideoFilePicker`, `pickExportSavePath`, etc.) - - Overrides `nativeBridgeClient` methods to return mock data - - Persists projects/docs in `localStorage` (`browser-shim-projects`, `browser-shim-document`) - - Auto-installs when running in a plain browser at `http://localhost:5173/?windowType=editor` - - Detected via absence of `window.electronAPI` - -### 2.4 Renderer UI (`src/components/ai-edition/`) - -| File | Purpose | -|------|---------| -| `IconRail.tsx` | Vertical 36-44px icon rail with collapse/expand chevron. Used for both left and right rails. Tooltip on hover. | -| `NewEditorShell.tsx` | **The default editor** for all users (replaces legacy `VideoEditor`). Layout: top header (project title + 3 toggle buttons) + body with left rail | left content (Project/Chat) | center (video + timeline) | right content (Transcript/Background/Video effects/Camera/Cursor/Crop/Export) | right rail. Recording → asset on editor open (auto-creates project + adds asset). Legacy `.openscreen` loading via the "Open" header button (migrates v2 → v3). | -| `AiEditionShell.tsx` | Re-exports `AiEditionOrLegacy` which delegates to `NewEditorShell` (legacy VideoEditor is now unused but kept for rollback). | -| `ProjectPanel.tsx` | Left content: project list + create input + assets list. Uses raw Tailwind matching OpenScreen's dark surface. | -| `TimelinePane.tsx` + `.module.css` | Ported from axcut `apps/web/src/components/TimelinePane.tsx` (~837 lines). Ruler, kept/cut segments, playhead, zoom (Ctrl+wheel), pan (Alt+drag), add cut, delete cut, resize cut handles, fit button, navigator overview. | -| `VirtualPreview.tsx` + `.module.css` | Ported from axcut `apps/web/src/components/VirtualPreview.tsx`. Single-video element with virtual-time seeking; seeks across clip boundaries; reports metadata via `onLoadedMetadata`; exposes video element via `onVideoElement` callback. | -| `TranscriptEditor.tsx` + `.module.css` | Click word / shift-click word → range → "Cut" button → `dropWordRange` op. Kept words = default, skipped = red strikethrough. | -| `ChatPanel.tsx` | Right content when `leftTab === "chat"`. Messages list + input + send. In-memory history. | -| `EditorSettings.tsx` | Bridge that wraps the **original `SettingsPanel`** (from `src/components/video-editor/SettingsPanel.tsx`, unchanged). Reads from `AxcutDocument.legacyEditor` (wallpaper, cursor, webcam, shadow, etc.), `document.zoomRanges`, `document.annotations`. Writes back through `setDocument` / `saveDocument`. Maps `activeTab` to `SettingsPanelMode` (background/effects/layout/cursor/timeline/export). Calls `SettingsPanel` with `hideInternalRail` so the right rail is the only navigation. | - -### 2.5 App-level wiring - -- `src/App.tsx` — imports and calls `installBrowserShims()` before render. The `editor` windowType still lazy-loads the `AiEditionShell` (which now renders `NewEditorShell`). -- `src/components/video-editor/featureFlags.ts` — renamed `AI_EDITION_ENABLED` → `AI_FEATURES_ENABLED`, default `false`. The flag now **only** gates the LLM/agent UI (chat panel). The new editor is the default for everyone. -- `package.json` — added `zod: ^3.23.8` and `zustand: ^5.0.8`. - -### 2.6 Documentation - -- `docs/architecture/ai-edition-merge-plan.md` — **major rewrite**: - - **New §0 Framing** — two layers (new editor = default, AI features = opt-in) - - **§5.8 locked decision** updated: flag now gates only LLM/agent UI - - **§10 cut-over** — no editor cut-over (new editor is default); only AI features opt-in - - Locked decisions list re-ordered: framing change recorded - ---- - -## 3. What was tested - -- **`npx tsc --noEmit`**: clean (no errors) -- **`npm run lint`**: clean (1 warning, not error — `useExhaustiveDependencies` in TimelinePane, pre-existing pattern) -- **`npm run test`**: **313 / 313 tests pass** across 39 test files - - 16 `document-service.test.ts` - - 15 `schema/index.test.ts` - - 14 `timeline.test.ts` - - 14 `migrate.test.ts` - - 8 `virtual-preview.test.ts` - - 5 `projectStore.test.ts` - - + 239 pre-existing tests (all still passing) -- **Browser smoke test**: `http://localhost:5173/?windowType=editor` renders the editor with shim data, project create/select works, asset add works (mocked), transcript/chat panels render, settings panel shows correct view per right-rail tab. - ---- - -## 4. Key decisions and rationale - -### 4.1 The framing change (user-driven) - -The original plan treated "AI-edition" as a single opt-in feature. Mid-implementation the user said: *multi-asset/clips/etc. is valid outside of user opt-in. It is valid outside of user opt-in. The opt-in should be limited to llm/conversation.* This led to: -- `AI_EDITION_ENABLED` → `AI_FEATURES_ENABLED` (the rename makes the semantic explicit) -- New editor ships to all users by default (kill-switch removed) -- The right rail's chat / LLM config is the only gated surface -- Local Whisper stays ungated (privacy-safe by construction) - -### 4.2 Why the new editor ships as the default despite incomplete feature parity - -The spec calls for full feature parity (annotations, zoom, cursor, webcam, blur, crop, export, legacy `.openscreen` loading). The implementation delivers the **architecture** and the **export, legacy loading, transcript, transcription, settings panel** integrations, but the new editor's UI is intentionally simpler than the legacy `VideoEditor` for some affordances (no annotations/zoom UI for adding new ones, just editing existing ones from the `SettingsPanel`). This is acceptable for a first cut because: -- The legacy `VideoEditor` is still on disk and reachable via git (rollback path) -- Adding the remaining UI affordances is incremental (no new architecture needed) -- The `SettingsPanel` integration already lets users edit every field that exists in their v3 document - -### 4.3 Why the AI runtime is stubbed - -Phases 6-8 require `@langchain/openai`, `@langchain/anthropic`, `deepagents`, `better-sqlite3`. These are heavy (multi-MB native modules, OAuth flows, langgraph runtime). The implementation: -- Ships the IPC contracts, provider registry, LLM config store (with `safeStorage`), chat history -- Stubs the actual LLM call (returns a fixed message reminding the user to install deps) -- The 8 providers, OAuth flow, reasoning effort mapping, and the chat-service scaffolding are all in place — adding the real `@langchain/*` calls is a focused follow-up - -### 4.4 Why ms for `annotations[]` / `zoomRanges[]` but sec for timeline - -`AxcutDocument.annotations` and `AxcutDocument.zoomRanges` mirror the legacy `ProjectEditorState.annotationRegions` / `.zoomRegions` which use **ms**. The timeline ops (`skipRanges`, `clips.sourceStartSec`, etc.) follow axcut's convention of **sec** because axcut's `clips` are authored from the agent/runtime where the second-based model is canonical. This dual-unit is contained to the document schema and handled by the `document/timeline.ts` math + `migrate.ts` conversion. The renderer reads `document.zoomRanges` directly as ms. - -### 4.5 Why `safeStorage` for credentials (not plain JSON) - -Per locked decision 4 in the spec: LLM credentials are stored in `safeStorage`-encrypted bytes (OS keychain on macOS, libsecret on Linux, DPAPI on Windows). Config (provider, model, baseUrl, reasoningEffort) is plain JSON. This matches axcut's security improvement over their original plain-JSON approach. - ---- - -## 5. What's NOT in this PR (deferred work) - -These are deliberate deferrals, not oversights: - -1. **Full feature parity UI** — adding new annotations/zoom regions from the new shell (the SettingsPanel can only edit existing ones). Follow-up: port the legacy `VideoEditor`'s annotation/zoom add flows to `NewEditorShell`. -2. **Real LLM calls** — `@langchain/*` deps not installed. Follow-up: `npm i @langchain/openai @langchain/anthropic deepagents` and replace the stub in `chat-service.ts:runChat`. -3. **SQLite for sessions/checkpoints** — `better-sqlite3` not installed. Follow-up: port axcut's `DatabaseService` and `PersistentFileCheckpointSaver`. -4. **Webcam real-time preview** in `VirtualPreview` — current is a single-video component; axcut has a two-layer crossfade. Follow-up for a richer preview experience. -5. **13-locale i18n** — the new components use hardcoded English strings ("Transcribe", "Remove cuts", "Export", etc.). Follow-up: add to `src/i18n/locales//*.json`. -6. **Settings sync to `userPreferences.ts`** — `AI_FEATURES_ENABLED` toggle is a constant, not user-toggleable. Follow-up: wire to the existing settings sync. -7. **Export dialog integration** — the new editor's "Export" button shows a toast. Follow-up: wire the `ExportDialog` component with the full options. -8. **The legacy `VideoEditor.tsx`** (2961 lines) is unchanged on disk. It can be deleted in a follow-up once confidence is high. - ---- - -## 6. How to continue - -### 6.1 Resume this branch - -```bash -cd G:\repos\openscreen\.worktrees\wt-9ce78f24 -git status # should be clean -git log --oneline -3 -npm run dev # already running, port 5173 -# Open http://localhost:5173/?windowType=editor -``` - -### 6.2 Add a real LLM provider - -1. `npm i @langchain/openai @langchain/anthropic deepagents better-sqlite3` -2. In `electron/ai-edition/chat-service.ts:runChat`, replace the stub with a real call: - ```ts - import { ChatOpenAI } from "@langchain/openai"; - const model = new ChatOpenAI({ model: config.model, apiKey }); - const result = await model.invoke(message); - ``` -3. Add the corresponding provider in `provider-registry.ts` if it's not already there. - -### 6.3 Add full feature parity (annotations/zoom creation UI) - -1. Port the legacy `VideoEditor`'s annotation-add flow (around line 2500+) to a new component. -2. Mount it in `NewEditorShell` alongside `SettingsPanel`. -3. Wire it to `documentStore.setDocument` (already wired through `EditorSettings`). - -### 6.4 Open a PR - -```bash -git push origin docs/ai-edition-plan # already pushed -gh pr create \ - --base main \ - --head docs/ai-edition-plan \ - --title "feat(ai-edition): implement v3 editor model + AI features scaffold" \ - --body-file PR_BODY.md -``` - -### 6.5 Delete the legacy `VideoEditor` when ready - -The file `src/components/video-editor/VideoEditor.tsx` (2961 lines) is now unused in the default flow. `grep -r "from.*VideoEditor" src/` to confirm. Then delete and remove from `App.tsx` lazy import. - ---- - -## 7. File map (where to look) - -``` -G:\repos\openscreen\.worktrees\wt-9ce78f24\ -├── docs/architecture/ -│ └── ai-edition-merge-plan.md # updated §0, §5.9, §10 -├── electron/ -│ ├── ai-edition/ -│ │ ├── document-service.ts # CRUD on .axcut files -│ │ ├── document-service.test.ts -│ │ ├── llm-config-store.ts # safeStorage credentials -│ │ ├── provider-registry.ts # 8 providers, static -│ │ └── chat-service.ts # in-memory, LLM stub -│ ├── ipc/ -│ │ ├── handlers.ts # wires services to bridge -│ │ └── nativeBridge.ts # adds aiEdition domain -│ └── native-bridge/services/ -│ └── aiEditionService.ts # bridge adapter -├── src/ -│ ├── App.tsx # installs browser shim -│ ├── native/ -│ │ ├── browserShim.ts # NEW - browser-mode stubs -│ │ ├── client.ts # adds aiEdition namespace -│ │ └── contracts.ts # adds aiEdition types -│ ├── components/ -│ │ ├── video-editor/ -│ │ │ ├── SettingsPanel.tsx # + hideInternalRail prop -│ │ │ └── featureFlags.ts # AI_EDITION_ENABLED → AI_FEATURES_ENABLED -│ │ └── ai-edition/ # NEW directory -│ │ ├── AiEditionShell.tsx # kill-switch removed -│ │ ├── NewEditorShell.tsx # main shell, the default -│ │ ├── IconRail.tsx -│ │ ├── ProjectPanel.tsx -│ │ ├── TimelinePane.tsx + .module.css -│ │ ├── VirtualPreview.tsx + .module.css -│ │ ├── TranscriptEditor.tsx + .module.css -│ │ ├── ChatPanel.tsx -│ │ └── EditorSettings.tsx # bridge → SettingsPanel -│ └── lib/ai-edition/ # NEW directory -│ ├── schema/index.ts + .test.ts -│ ├── document/ -│ │ ├── timeline.ts + .test.ts -│ │ ├── migrate.ts + .test.ts -│ │ ├── transcribe.ts -│ │ └── ids.ts -│ ├── timeline/ -│ │ └── virtual-preview.ts + .test.ts -│ ├── store/ -│ │ └── projectStore.ts + .test.ts -│ └── exporter/ -│ └── documentExporter.ts -└── package.json # +zod, +zustand -``` - ---- - -## 8. The conversation arc (for context) - -1. User asked to check PR #35 and start implementation per its plan. -2. Implemented Phase 0 (schema, migration, feature flag) — 29 tests pass, human-testable via dev server. -3. Implemented PR 1.1 (project panel, document service, IPC bridge) — human-testable. -4. User asked for total spec completion. Implemented PR 1.2 + 1.3 (timeline port, preview port, new editor shell with kill-switch). -5. User said "implement 1, 2, and 3" with the axcut `\\wsl.localhost\Ubuntu\home\etienne\repos\axcut\` path. Implemented: - - Export (Phase 3) — adapter to existing VideoExporter - - Legacy `.openscreen` loading — migrate v2 → v3 - - Settings panel (annotations, zoom, cursor, webcam, wallpaper) — bridge to `SettingsPanel` -6. User said "go on → full implementation". Implemented Phases 6-8 scaffolding (provider registry, LLM config store with safeStorage, chat service stub, IPC contracts) and Phase 9 partial (settings toggle, i18n deferred). -7. User asked to relaunch in browser. Added `browserShim.ts` for `http://localhost:5173/?windowType=editor`. -8. User asked for UI redesign to match original OpenScreen + axcut layout. Implemented: - - Left icon rail (Project / Chat) - - Right icon rail (Transcript / Background / Video effects / Camera / Cursor / Crop / Export) - - Top header (project title + PanelLeft / PanelRight / Download) - - NewEditorShell with full-height columns - - Removed the chevron collapse buttons (user requested) - - Used original OpenScreen SettingsPanel icons - - Added `hideInternalRail` prop so the right rail is the only navigation -9. User asked about worktree, branch, commit, push. Confirmed branch (`docs/ai-edition-plan`), committed and pushed. -10. User asked for a handoff summary in English for a coding agent. - ---- - -**The next coding agent should**: -- Open `http://localhost:5173/?windowType=editor` to see the current state -- Read `docs/architecture/ai-edition-merge-plan.md` for the plan -- Pick up from §5 (deferred work) — most impactful next steps are real LLM calls (#2) and feature parity UI (#1) -- All architecture is in place; the remaining work is wiring and UI polish, not new design diff --git a/AGENTS.md b/AGENTS.md index 417f937e5..babd479cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,7 @@ OpenScreen is a free, open-source screen recorder and video editor (Electron + R - `src/` — React app: UI, editor components, timeline, i18n, captioning/cursor/exporter libs - `electron/` — main process, IPC, recording orchestration - `electron/native/` — **native** capture helpers: `screencapturekit/` (Swift, macOS) and `wgc-capture/` (C++/Win32, Windows). These are built and shipped with the app, not loaded from npm -- `docs/` — architecture, engineering roadmaps, testing guides +- `technical-documentation/` — architecture, engineering and testing reference (start at its README) - `tests/` — Playwright e2e specs + fixtures - `scripts/` — native build scripts, diagnostic tools - `nix/`, `flake.nix` — Linux packaging @@ -98,7 +98,7 @@ Two `workflow_dispatch` workflows cut a release with a pre-release candidate (RC - **Promote RC**: Actions → "Promote RC to stable release" → Run workflow. Input: `rc_tag` (e.g. `v1.5.0-rc.2`), optional `release_notes_extra`. Closes the `vX.Y.Z` milestone, strips `-rc.N` from `package.json`, pushes `vX.Y.Z` tag, which triggers `build.yml` to publish a stable release (full notarization, Tier 3 homebrew/winget/nix/aur fires). Notifies `#announcements` on Discord. - **Manual fallback**: `git tag vX.Y.Z-rc.N && git push origin vX.Y.Z-rc.N` does the same as Cut RC (minus the milestone migration and Discord announce) — useful for emergency cuts. -Both workflows require the `OPENSCREEN_RELEASE_TOKEN` secret (a fine-grained PAT with `contents: write` + `issues: write`). This is the standard fix for `release: published` not triggering downstream workflows when the release is created by `GITHUB_TOKEN`. See `docs/secrets.md`. +Both workflows require the `OPENSCREEN_RELEASE_TOKEN` secret (a fine-grained PAT with `contents: write` + `issues: write`). This is the standard fix for `release: published` not triggering downstream workflows when the release is created by `GITHUB_TOKEN`. See `technical-documentation/engineering/release-and-secrets.md`. **Release branches freeze the build between cut and promote.** Every RC cut creates `release/vX.Y.Z-rc.N`. The branch is *not* merged into `main` until the stable tag is published; only cherry-picks of bugfixes land on the release branch during the RC window. The stable tag points at the branch tip (RC + cherry-picks), then `promote.yml` opens a `release/vX.Y.Z-sync → main` PR to bring main into line. This contract exists because of the v1.6.0 incident (2026-07-05) where the original promote workflow tagged `main` instead of the RC snapshot, causing 23 unreleased commits to ship in `v1.6.0`. Full rules in `.harness/docs/git-workflow.md` § Release branches. diff --git a/electron/media/ffmpegExportIpc.ts b/electron/media/ffmpegExportIpc.ts index ce82342fb..d07287955 100644 --- a/electron/media/ffmpegExportIpc.ts +++ b/electron/media/ffmpegExportIpc.ts @@ -15,7 +15,7 @@ import { * sandboxed and stays that way. Dropping the sandbox (option A') was measured * and buys nothing: with the crossing at exactly zero the pipeline still loses * to WebCodecs, because the wall is the compositor, not this path. See - * docs/architecture/export-pipeline.md §5. + * technical-documentation/architecture/export-pipeline.md * * This whole path is REFUTED (§5): feeding native ffmpeg from the renderer is * 2.1x SLOWER than what we ship. It survives as bench scaffolding, not as a diff --git a/electron/native/README.md b/electron/native/README.md index 6b20fd8aa..9c450339d 100644 --- a/electron/native/README.md +++ b/electron/native/README.md @@ -29,7 +29,7 @@ The current helper implementation supports display/window ScreenCaptureKit video Electron exposes `is-native-mac-capture-available` for capability probing. It resolves the same helper locations listed above and reports `missing-helper` until a Swift helper binary is present. When available, macOS recording routes screen/window capture through the native helper so editable cursor recordings do not bake the system cursor into the video. Cursor positions are sampled in Electron; when the cursor helper is available and Accessibility is granted, samples are also tagged with link/text cursor hints such as `pointer`. -See `docs/engineering/macos-native-recorder-roadmap.md` for the contract, rollout phases, and SSOT rules. +See `technical-documentation/architecture/recording.md` for the contract, rollout phases, and SSOT rules. ## Windows @@ -119,5 +119,5 @@ Remove-Item Env:OPENSCREEN_WGC_TEST_MICROPHONE_DEVICE_NAME ## STT helper The speech-to-text helper (`whisper-stt-server`) is built separately from the -capture helpers. See `docs/engineering/stt-spec.md` for the architecture and +capture helpers. See `technical-documentation/architecture/transcription-and-captions.md` for the architecture and `scripts/build-whisper-stt.sh` for the build command. diff --git a/electron/stt/index.ts b/electron/stt/index.ts index a186886cd..4f3e992aa 100644 --- a/electron/stt/index.ts +++ b/electron/stt/index.ts @@ -18,7 +18,7 @@ import { WhisperServerManager } from "./whisperServer"; * word-level segments in one pass (see whisperServer.ts). Word * timestamps come from whisper.cpp's native DTW token timestamps * (`t_dtw`, SMALL aheads preset, `flash_attn = false`), see - * docs/engineering/stt-spec.md § Decision rationale. + * technical-documentation/architecture/transcription-and-captions.md § Decision rationale. * 3. `shutdown()` tears down on app quit. * * Status events fan out via `statusSink` so the renderer can drive its diff --git a/electron/stt/modelManager.ts b/electron/stt/modelManager.ts index 7ad7207d5..8ec47652e 100644 --- a/electron/stt/modelManager.ts +++ b/electron/stt/modelManager.ts @@ -21,7 +21,7 @@ import { pipeline } from "node:stream/promises"; * to prevent partial downloads from being treated as complete. * * Word timestamps come from whisper.cpp's native DTW token timestamps, so no - * separate VAD model is required. See `docs/engineering/stt-spec.md`. + * separate VAD model is required. See `technical-documentation/architecture/transcription-and-captions.md`. */ export type SttModelId = "whisper"; diff --git a/electron/stt/transcriptionContract.ts b/electron/stt/transcriptionContract.ts index 49767af68..85b6c7152 100644 --- a/electron/stt/transcriptionContract.ts +++ b/electron/stt/transcriptionContract.ts @@ -12,7 +12,7 @@ /** A word-level segment with timestamps from whisper.cpp's native DTW token * timestamps (`t_dtw`, computed with the SMALL aheads preset — see - * docs/engineering/stt-spec.md § Decision rationale). Absolute seconds + * technical-documentation/architecture/transcription-and-captions.md § Decision rationale). Absolute seconds * in the source recording. */ export interface SttWordSegment { word: string; diff --git a/poc-d3d/.gitignore b/poc-d3d/.gitignore index e812f9cec..f7e4e976d 100644 --- a/poc-d3d/.gitignore +++ b/poc-d3d/.gitignore @@ -9,7 +9,7 @@ *.raw *.nv12 -# médias de fixture (régénérables via docs/S1-sources.md ; fixture.json est suivi) +# médias de fixture (provenance dans fixture/fixture.json, qui est suivi) fixture/*.mp4 fixture/*.cursor.json diff --git a/poc-d3d/README.md b/poc-d3d/README.md index f754356fb..cc69c8a2c 100644 --- a/poc-d3d/README.md +++ b/poc-d3d/README.md @@ -2,7 +2,7 @@ Troisième POC de rendu d'OpenScreen, à côté de [`poc/`](../poc) (web, WebCodecs + WebGPU) et [`poc-native/`](../poc-native) (Rust + wgpu/Vulkan). Voir la spec : -[`docs/architecture/rendering-architecture.md`](../docs/architecture/rendering-architecture.md), +[`technical-documentation/engineering/rendering-performance.md`](../technical-documentation/engineering/rendering-performance.md), annexe D (D.6 en particulier). **Ce qu'il prouve.** Le chemin natif GPU-résident — celui que `poc-native` a montré bloqué @@ -22,7 +22,7 @@ NV12→RGB BT.709, coins arrondis + masques (SDF), ombres portées (pénombre SD **Résultat mesuré** (protocole §C.2 du doc : régime soutenu, tour de chauffe jeté, spread < 15 %) : config tous-effets **~126 fps** en 1080p60, au-dessus du web (79) et de wgpu (48–68). Le fps enveloppe demux → décode → composite → encode → mux (§10 : une lecture -d'horloge avant/après tout le run). Détail des couches C0→C8 : `docs/S6-report.md`. +d'horloge avant/après tout le run). Détail des couches C0→C8 : [`technical-documentation/architecture/native-compositor.md`](../technical-documentation/architecture/native-compositor.md). C'est le **fast-path natif retenu** pour Windows (cf. le marqueur de décision dans l'annexe D). `poc/` reste l'hôte de lancement portable ; `poc-native` reste la preuve de portabilité du @@ -31,9 +31,9 @@ compositeur (WGSL natif à l'identique) + la carte des coûts. ## Stack - **Rust + windows-rs**, D3D11 nu (feature level 11_1, `VIDEO_SUPPORT`, multithread-protected). - Décision framework en `docs/S0-frameworks.md` (Vulkan/Direct2D/GStreamer/wgpu instruits, écartés). + Décision framework en [`technical-documentation/architecture/native-compositor.md`](../technical-documentation/architecture/native-compositor.md) (Vulkan/Direct2D/GStreamer/wgpu instruits, écartés). - **ffmpeg (libav\*)** LGPL pour demux / décode D3D11VA / encode `h264_amf` / mux. Bindings - générés par `bindgen` (choix vs `ffmpeg-next` : suit ffmpeg 8.x — voir `docs/S2-c0.md`), + générés par `bindgen` (choix vs `ffmpeg-next` : suit ffmpeg 8.x — voir [`technical-documentation/architecture/native-compositor.md`](../technical-documentation/architecture/native-compositor.md)), shim C (`shim.c`) pour les structs opaques. - Compositeur HLSL (`src/shaders.hlsl`) compilé au runtime. @@ -41,7 +41,9 @@ compositeur (WGSL natif à l'identique) + la carte des coûts. - Rust (toolchain msvc), Visual Studio (MSVC + Windows SDK), LLVM (libclang, pour bindgen). - **Build ffmpeg LGPL-shared** dans `thirdparty/` (non versionné) : récupérer - `ffmpeg-master-latest-win64-lgpl-shared` (releases BtbN/FFmpeg-Builds), dézipper dans + `ffmpeg-n8.1.2-win64-lgpl-shared` (le build pinné dans `.cargo/config.toml` — le + MÊME que `scripts/fetch-ffmpeg.mjs` vendorise, sinon le require() de l'addon échoue), + dézipper dans `thirdparty/`. Le chemin est relatif au dossier, fixé dans `.cargo/config.toml` (`FFMPEG_DIR`). `LIBCLANG_PATH` y pointe l'install LLVM. Ajuste le chemin vcvars dans `x.bat` si besoin. @@ -58,7 +60,7 @@ x.bat run --release [-- --fixture fixture --out out] Fenêtre native : preview du compositing en lecture bouclée (swapchain DXGI flip, blit zéro-copie du RT), sélecteur de preset C0→C8, Play/Pause, **Export** (barre de progression + -bilan _temps + fps_). Écrit `out/export.mp4`. Détail : `docs/S7-preview-export.md`. +bilan _temps + fps_). Écrit `out/export.mp4`. Détail : [`technical-documentation/architecture/native-compositor.md`](../technical-documentation/architecture/native-compositor.md). **Bench (§9/§10)** — la mesure fps headless, inchangée : @@ -73,11 +75,13 @@ Produit `out/C{0..8}.mp4` (1080p60, 360 frames), `out/C{n}_f{60,180,300}.png`, Deux flux screen (le 2ᵉ simule une webcam HQ), 1080p60 CBP, 360 frames, coupés en `-c copy`. Médias non versionnés (convention des autres POC) — provenance et commandes de régénération -dans `docs/S1-sources.md` ; `fixture/fixture.json` (le manifeste mesuré) est suivi. +dans `fixture/fixture.json`, qui est suivi. ## Docs -`docs/` = le parcours S0→S7 du POC : S0 décision framework, S1 sources/chaîne matérielle, -S2 pipeline C0, S6 rapport + mesure des moteurs GPU + optimisations, S7 preview/export -interactive (marche vers l'intégration app). `spikes/` = les probes jetables de S0 +L'architecture du compositeur est documentée dans +[`technical-documentation/architecture/native-compositor.md`](../technical-documentation/architecture/native-compositor.md), +et les mesures qui l'ont choisie dans +[`technical-documentation/engineering/rendering-performance.md`](../technical-documentation/engineering/rendering-performance.md). +Ce README ne couvre que le build et le run de la crate. `spikes/` = les probes jetables (Direct2D, NV12 render-target) conservés comme preuve. diff --git a/scripts/build-whisper-stt.sh b/scripts/build-whisper-stt.sh index 7041e6f5b..2e8ec5ffe 100644 --- a/scripts/build-whisper-stt.sh +++ b/scripts/build-whisper-stt.sh @@ -6,7 +6,7 @@ # The helper is a long-lived HTTP server that exposes the same # spawn -> GET / -> POST /inference contract the previous native STT helper # used, but links libwhisper directly and reads whisper.cpp's DTW token timestamps. -# See docs/engineering/stt-whispercpp-migration-plan.md §2. +# See technical-documentation/architecture/transcription-and-captions.md # # Local use: # bash scripts/build-whisper-stt.sh # default backend for host diff --git a/scripts/fetch-ffmpeg.mjs b/scripts/fetch-ffmpeg.mjs index c9fc30cf0..8fa81c34a 100644 --- a/scripts/fetch-ffmpeg.mjs +++ b/scripts/fetch-ffmpeg.mjs @@ -41,7 +41,8 @@ // NOTE: the plan this was vendored for is REFUTED. Feeding native ffmpeg from // the renderer measured 2.1x SLOWER than the WebCodecs path it was to replace — // the wall is the compositor, not the encoder. See -// docs/architecture/export-pipeline.md §5. The binary stays because the bench's +// technical-documentation/engineering/rendering-performance.md. The binary stays +// because the bench's // `native` arms use it, and because a future native core would still need a // licence-gated H.264 encoder; nothing here ships on the export path today. // @@ -326,7 +327,7 @@ async function main() { console.error( "macOS is not provisioned by this script: BtbN publishes no macOS build.\n" + "It would have to be built and notarised separately. Note the native-encode plan\n" + - "is refuted (docs/architecture/export-pipeline.md §5), so this is bench-only today.", + "is refuted (technical-documentation/engineering/rendering-performance.md), so this is bench-only today.", ); process.exit(1); } diff --git a/src/components/ai-edition/PreviewCanvas.tsx b/src/components/ai-edition/PreviewCanvas.tsx index 52f2fda22..90744014c 100644 --- a/src/components/ai-edition/PreviewCanvas.tsx +++ b/src/components/ai-edition/PreviewCanvas.tsx @@ -406,7 +406,7 @@ export function PreviewCanvas(props: PreviewCanvasProps) { // VirtualPreview path — CSS-transformed