@hypit/hypit 0.2.5 → 0.2.7

package/packages/script/src/surface.ts

@@ -24,6 +24,10 @@ function findClose(input: ScriptSurfaceInput): { readonly start: number; readonl
   const close = `</${input.tag}>`;
   let cursor = input.contentStart;
   while (cursor < input.source.length) {
+    if (input.source[cursor] === "\\") {
+      cursor += 2;
+      continue;
+    }
     if (input.source.startsWith("<!--", cursor)) {
       const commentEnd = input.source.indexOf("-->", cursor + 4);
       if (commentEnd < 0) {
@@ -33,9 +37,7 @@ function findClose(input: ScriptSurfaceInput): { readonly start: number; readonl
       continue;
     }
     if (input.source.startsWith(close, cursor)) {
-      let slashes = 0;
-      for (let before = cursor - 1; before >= 0 && input.source[before] === "\\"; before -= 1) slashes += 1;
-      if (slashes % 2 === 0) return { start: cursor, end: cursor + close.length };
+      return { start: cursor, end: cursor + close.length };
     }
     cursor += 1;
   }

package/packages/script/src/types.ts

@@ -35,7 +35,7 @@ export type ParsedSegment = NarrativeSegment & {
   readonly index: number;
   readonly atoms: readonly ParsedAtom[];
   readonly range: SourceRange;
-  /** Exact body range between the Segment tags, used only for source-preserving marker edits. */
+  /** Exact body range between Segment tags for Script-owned source edits and formatting. */
   readonly contentRange: SourceRange;
   readonly selfClosing: boolean;
 };

package/packages/source/README.md

@@ -9,5 +9,5 @@ It recognizes exactly one mandatory bounded Header:
 ```
 
 The Header selects an exact trusted Frontend. There is no suffix dispatch and no default parser.
-The package masks the Header while preserving character offsets, but does not recognize imports,
+The package masks the Header while preserving UTF-16 source offsets and line breaks, but does not recognize imports,
 XML, Script, Recipes, Run syntax or domain Types. Those belong to the selected Frontend.

package/packages/source/src/header.ts

@@ -75,6 +75,7 @@ export function parseSourceHeader(sourceName: string, text: string): SourceHeade
 
 /** Preserve every original offset while making the Header ordinary whitespace to body Frontends. */
 export function maskSourceHeader(text: string, header: SourceHeader): string {
-  const prefix = text.slice(0, header.end).replace(/[^\r\n]/gu, " ");
+  // Source ranges use UTF-16 offsets: replace each code unit, not each code point.
+  const prefix = text.slice(0, header.end).replace(/[^\r\n]/g, " ");
   return `${prefix}${text.slice(header.end)}`;
 }

package/packages/studio/README.md

@@ -1,5 +1,13 @@
 # Hypit Studio
 
+For direct picture inspection, `hypit snapshot --studio <studio-url>` reads the current compiled
+`HyperframesDocument` from `GET /__studio/document` and its existing `/__studio/material/<resource>`
+resources. `GET /__studio/visual.html` exposes the same materialized picture without the interactive
+Studio playback shim or audio. Both representations come from the same compilation as the displayed
+preview. The snapshot invocation uses the selected Runtime Profile's frame Provider and creates no
+Build. During a pending Source compilation the export route reports that state; a failed update
+reports its error instead of returning the previous picture as current.
+
 The single official Web Studio for SVML. It opens an explicit Run Source,
 traces its Film or Render target back to the semantic and visual projections
 Studio can edit, runs deterministic Producers and explicitly permitted transient Needs, and composites the
@@ -159,6 +167,11 @@ the selected entity. A reference can resolve to a shared Frame or Recipe, so one
 may affect several consumers. Structured fields save together when editing ends and the value is complete; missing required values stay in the editor with a completion hint.
 Check save status; source conflicts reject stale edits rather than overwrite newer files.
 
+Script source ranges come from its raw Surface and Companion. Marker edits use Script's parsed
+anchors and preserve unrelated prose, whitespace and word attributes; the displayed timeline words
+are not a replacement text source. Recipe parameter reads use the same Source Header preparation
+as compilation, preserving UTF-16 offsets for the exact property being edited.
+
 The Timeline owns the editor's complete range; displayed objects do not extend it. Take placement
 and complete extent are reference information in Studio.
 

package/packages/studio/src/feedback-server.ts

@@ -3,6 +3,7 @@ import { relative } from "node:path";
 import type { Plugin } from "vite";
 import { createFeedbackStore, FeedbackConflict } from "./feedback-store.js";
 import { readFeedbackMutation } from "./feedback.js";
+import { allowsStudioMutation } from "./mutation-origin.js";
 import type { FeedbackDocument, FeedbackView } from "./feedback.js";
 
 /** Review storage is separate from compilation, Results and Agent delivery. */
@@ -23,6 +24,12 @@ export function studioFeedbackPlugin(workspaceRoot: string, runPath: string): Pl
       server.httpServer?.once("close", () => watcher.close());
       server.middlewares.use((request, response, next) => {
         if (new URL(request.url ?? "/", "http://studio.hypit.local").pathname !== "/__studio/feedback") return next();
+        if (request.method === "POST" && !allowsStudioMutation(request.headers)) {
+          response.statusCode = 403;
+          response.setHeader("content-type", "application/json; charset=utf-8");
+          response.end(JSON.stringify({ error: "Studio mutation must come from this local Studio session." }));
+          return;
+        }
         response.setHeader("content-type", "application/json; charset=utf-8");
         response.setHeader("cache-control", "no-store");
         void (async () => {

package/packages/studio/src/mutation-origin.ts

@@ -0,0 +1,20 @@
+import type { IncomingHttpHeaders } from "node:http";
+
+/** Studio writes belong to the local page serving this Studio session. */
+export function allowsStudioMutation(headers: IncomingHttpHeaders): boolean {
+  const host = headers.host;
+  if (host === undefined) return false;
+  let target: URL;
+  try { target = new URL(`http://${host}`); } catch { return false; }
+  if (!["localhost", "127.0.0.1", "[::1]"].includes(target.hostname) || target.host !== host.toLowerCase()) return false;
+
+  const origin = headers.origin;
+  if (origin !== undefined) {
+    let source: URL;
+    try { source = new URL(origin); } catch { return false; }
+    if (source.origin !== origin || source.origin !== target.origin) return false;
+  }
+
+  const site = headers["sec-fetch-site"];
+  return site === undefined || site === "same-origin" || site === "none";
+}

package/packages/studio/src/parameters.ts

@@ -17,6 +17,7 @@ import type {
 } from "@hypit/studio-adapter";
 import { parseSvs } from "@hypit/svs";
 import { parseOpeningTag } from "@hypit/markup";
+import { prepareAuthorSource } from "@hypit/elaborator";
 import { parameterControlForSchema, parameterRecordSchema } from "./parameter-values.js";
 import type { CanonicalValue } from "@hypit/protocol";
 
@@ -132,12 +133,6 @@ function sourceAbsolute(root: string, path: string, base?: string): string {
   return resolve(directory, path);
 }
 
-function svsText(source: string): string {
-  const header = /^\s*<\?svml[\s\S]*?\?>/u.exec(source);
-  if (header === null) return source;
-  return `${header[0].replace(/[^\r\n]/gu, " ")}${source.slice(header[0].length)}`;
-}
-
 function recipeParameters(input: {
   readonly root: string;
   readonly files: readonly StudioSourceFile[];
@@ -176,7 +171,8 @@ function recipeParameters(input: {
   const source = sourceFor(input.root, imported.source, input.files, input.current.path);
   if (source === undefined || source.language !== "svs") return [];
   const recipePath = parts.join(".");
-  const parsed = parseSvs(source.path, svsText(source.text));
+  const prepared = prepareAuthorSource({ id: source.path, name: source.path, text: source.text });
+  const parsed = parseSvs(source.path, prepared.text);
   const recipe = parsed.recipes.find((item) => item.value.path === recipePath);
   if (recipe === undefined) return [];
   return input.recipe.bindings.flatMap((declaration): readonly StudioSourceBinding[] => {

package/packages/studio/src/preview/render.ts

@@ -1,5 +1,6 @@
 import type { AudioTrack, Composition } from "@hypit/composition";
 import { compileHyperframesDocument, materializeHyperframesHtml } from "@hypit/hyperframes";
+import type { HyperframesDocument } from "@hypit/hyperframes";
 import type { ProgramSpace } from "@hypit/program-space";
 
 import { injectRuntimeShim } from "./runtime-shim.js";
@@ -19,6 +20,11 @@ export type RenderInput = {
  * material all come from the projection selected by the Run.
  */
 export function renderPreview(input: RenderInput): string {
+  return renderStudioProgramme(input).preview;
+}
+
+/** The same compiled picture serves immediate frame capture and interactive playback. */
+export function renderStudioProgramme(input: RenderInput): { readonly document: HyperframesDocument; readonly html: string; readonly preview: string } {
   const document = compileHyperframesDocument(input.composition, input.space);
   const html = materializeHyperframesHtml(document, (artifact) => {
     // The only Artifacts a preview can reference are files the author already
@@ -51,5 +57,5 @@ export function renderPreview(input: RenderInput): string {
         fadeInSamples: clip.fadeInSamples, fadeOutSamples: clip.fadeOutSamples,
       }))}"></audio>`;
     }).join("");
-  return injectRuntimeShim(html, audio);
+  return { document, html, preview: injectRuntimeShim(html, audio) };
 }

package/packages/studio/src/server.ts

@@ -15,6 +15,7 @@ import type { ServedFile } from "./compile.js";
 import type { StudioDomain } from "./domain.js";
 import type { StudioCompanionRegistry } from "./studio-registry.js";
 import { loadStudioRun } from "./run.js";
+import { allowsStudioMutation } from "./mutation-origin.js";
 import { parameterAuthorValue, parameterOption, serializeParameterValue, serializeAttributeGroup, validateParameterValue } from "./parameter-values.js";
 import { readStudioSession } from "./session.js";
 import type { Range, StudioFailure, StudioLibraryRequest, StudioLibraryView, StudioMutation, StudioSnapshot } from "./shared.js";
@@ -80,6 +81,8 @@ class StudioMutationRejected extends Error {}
 
 export function studioPlugin(options: StudioPluginOptions): Plugin {
   let snapshot: StudioSnapshot | undefined;
+  let visualHtml: string | undefined;
+  let visualDocument: import("@hypit/hyperframes").HyperframesDocument | undefined;
   let failure: StudioFailure | undefined;
   let material: ReadonlyMap<string, ServedFile> = new Map();
   let revision = 0;
@@ -158,6 +161,8 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
       if (attempt !== requestedRevision) return;
       revision = attempt;
       snapshot = result.snapshot;
+      visualHtml = result.visualHtml;
+      visualDocument = result.document;
       material = result.material;
       failure = undefined;
       if (notify) server?.ws.send({ type: "custom", event: "studio:snapshot", data: snapshot });
@@ -473,6 +478,10 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
       value.middlewares.use((request, response, next) => {
         const url = new URL(request.url ?? "/", "http://studio.hypit.local");
         if (request.method === "PUT" && url.pathname === "/__studio/source") {
+          if (!allowsStudioMutation(request.headers)) {
+            json(response, 403, { error: "Cross-origin Studio mutations are prohibited." });
+            return;
+          }
           void (async () => {
             let acquired = false;
             try {
@@ -524,6 +533,10 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
           return;
         }
         if (request.method === "PUT" && url.pathname === "/__studio/artifact-name") {
+          if (!allowsStudioMutation(request.headers)) {
+            json(response, 403, { error: "Cross-origin Studio mutations are prohibited." });
+            return;
+          }
           void (async () => {
             try {
               const chunks: Buffer[] = [];
@@ -546,6 +559,10 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
           return;
         }
         if (request.method === "POST" && url.pathname === "/__studio/mutation") {
+          if (!allowsStudioMutation(request.headers)) {
+            json(response, 403, { error: "Cross-origin Studio mutations are prohibited." });
+            return;
+          }
           void (async () => {
             try {
               const chunks: Buffer[] = [];
@@ -580,6 +597,28 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
           next();
           return;
         }
+        if (url.pathname === "/__studio/visual.html" || url.pathname === "/__studio/document") {
+          void (async () => {
+            if (timer !== undefined || publishing > 0) {
+              json(response, 409, { error: "Studio is compiling a Source change; capture after the updated preview is ready." });
+              return;
+            }
+            if (snapshot === undefined && failure === undefined) await publish(++requestedRevision);
+            if (failure !== undefined || visualHtml === undefined) {
+              json(response, 500, failure ?? { error: "Studio has no compiled picture." });
+              return;
+            }
+            if (url.pathname === "/__studio/document") {
+              json(response, 200, visualDocument);
+              return;
+            }
+            response.statusCode = 200;
+            response.setHeader("content-type", "text/html; charset=utf-8");
+            response.setHeader("cache-control", "no-store");
+            response.end(request.method === "HEAD" ? undefined : visualHtml);
+          })();
+          return;
+        }
         if (url.pathname === "/__studio/session") {
           void (async () => {
             if (snapshot === undefined && failure === undefined) {

package/packages/studio/src/session.ts

@@ -9,7 +9,7 @@ import type { ServedFile } from "./compile.js";
 import type { StudioDomain } from "./domain.js";
 import type { Observations } from "./observe.js";
 import { preview } from "./programme.js";
-import { renderPreview } from "./preview/render.js";
+import { renderStudioProgramme } from "./preview/render.js";
 import type { RunPlan } from "./run.js";
 import type { StudioSnapshot } from "./shared.js";
 import type { StudioCompanionRegistry } from "./studio-registry.js";
@@ -47,6 +47,8 @@ function sourceFiles(run: RunPlan): readonly StudioSourceFile[] {
 
 export type StudioSession = {
   readonly snapshot: StudioSnapshot;
+  readonly document: import("@hypit/hyperframes").HyperframesDocument;
+  readonly visualHtml: string;
   readonly material: ReadonlyMap<string, ServedFile>;
   readonly observations: Observations;
   readonly projections: readonly StudioViewRequirement[];
@@ -77,7 +79,7 @@ export async function readStudioSession(input: {
     projections: inspection.projections,
     ...(input.transientExecution === undefined ? {} : { transientExecution: input.transientExecution }),
   });
-  const rendered = renderPreview({
+  const rendered = renderStudioProgramme({
     composition: built.composition,
     space: built.space as never,
     served: new Set(built.served.keys()),
@@ -85,6 +87,8 @@ export async function readStudioSession(input: {
   const text = readFileSync(input.run.authorSource, "utf8");
   const files = sourceFiles(input.run);
   return {
+    document: rendered.document,
+    visualHtml: rendered.html,
     snapshot: snapshot(input.registry, built, {
       revision: input.revision,
       path: input.sourcePath ?? input.run.authorSource,
@@ -99,7 +103,7 @@ export async function readStudioSession(input: {
       },
       canvas: built.canvas,
       frameRate: built.frameRate,
-      preview: { kind: "hyperframes", srcdoc: rendered },
+      preview: { kind: "hyperframes", srcdoc: rendered.preview },
       workspaceRoot: input.workspaceRoot,
       sourceFiles: files,
       surfaces: input.domain.surfaces,

package/packages/studio/src/ui/syntax.ts

@@ -1,9 +1,8 @@
 /**
  * A tokenizer for SVML's own surface syntax.
  *
- * SVML has a small, closed grammar — tags, quoted strings, whole-value
- * references, and Script prose with markers — so it is tokenized directly rather
- * than through a general highlighter that has no grammar for it. The Script
+ * Recognize the common Markup shell and Script prose for highlighting, without
+ * validating package-owned Surfaces. The Script
  * markers are the point: `@{claim} … @{/claim}` is what a Media Item binds to, so it
  * has to read as a distinct thing from an ordinary attribute.
  *
@@ -105,8 +104,7 @@ export function tokenizeSvml(source: string): readonly Token[] {
       cursor = nameStart + name[0].length;
       cursor = tokenizeAttributes(source, cursor, push);
 
-      // Script is the language's one Raw Surface: its body is prose with
-      // markers, not markup, and must be scanned by different rules.
+      // Script's Raw Surface has its own prose grammar.
       if (!closing && localName(name[0]) === "script" && source[cursor - 2] !== "/") {
         cursor = tokenizeScriptBody(source, cursor, name[0], push);
       }
@@ -167,6 +165,7 @@ function tokenizeAttributes(source: string, from: number, push: Push): number {
 function tokenizeScriptBody(source: string, from: number, tag: string, push: Push): number {
   const close = `</${tag}>`;
   let cursor = from;
+  let inSegment = false;
   while (cursor < source.length) {
     if (source[cursor] === "\\") { cursor += 2; continue; }
     if (source.startsWith(close, cursor)) {
@@ -199,14 +198,16 @@ function tokenizeScriptBody(source: string, from: number, tag: string, push: Pus
       }
       const closing = source[cursor + 1] === "/";
       const nameStart = cursor + (closing ? 2 : 1);
-      const name = NAME.exec(source.slice(nameStart));
-      if (name === null) { cursor += 1; continue; }
       const end = source.indexOf(">", nameStart);
       const stop = end < 0 ? source.length : end + 1;
+      const selfClosing = end >= 0 && source[end - 1] === "/";
+      const nameEnd = end < 0 ? stop : end - (selfClosing ? 1 : 0);
       push(cursor, nameStart, "punct");
-      // An upper-case tag inside Script is a Role Cue, not a Segment.
-      push(nameStart, nameStart + name[0].length, /^[A-Z]/u.test(name[0]) ? "role" : "tag");
-      push(nameStart + name[0].length, stop, "punct");
+      // Context distinguishes Segments from Role Cues, regardless of language or case.
+      push(nameStart, nameEnd, inSegment && !closing ? "role" : "tag");
+      push(nameEnd, stop, "punct");
+      if (closing) inSegment = false;
+      else if (!inSegment && !selfClosing) inSegment = true;
       cursor = stop;
       continue;
     }

package/packages/temporal-markup/EDITING.md

@@ -164,7 +164,7 @@ write target. The `fixed` case means no temporal gesture writes that endpoint, n
 parameter editing is forbidden.
 
 - `@hypit/script` owns tokenization, anchor identities, legal marker sites, and structural writeback.
-  It normalizes equivalent marker whitespace, retains punctuation and attributes, writes coincident
+  It relocates markers without rewriting unrelated prose whitespace, retains punctuation and attributes, writes coincident
   markers together, and preserves all unrelated relationships and caption information.
 - `@hypit/temporal-markup` owns the interpretation of each time form and declares its write targets.
   Direct semantic references expose semantic targets; quoted time expressions expose parameter

package/packages/video-cli/README.md

@@ -1,8 +1,8 @@
 # `@hypit/video-cli`
 
 Official video command application. It selects the Markup compiler Host and supplies one editable
-starter Runtime Profile. The CLI still imports no Provider or Store implementation; installed packages
-are activated only by explicit Source imports or Profile `use` entries.
+starter Runtime Profile. Execution Endpoints are selected by Profile `use` entries; Source imports
+activate author packages. Immediate tools own their temporary input/output resource storage.
 
 Every Frontend, Surface, deterministic Producer and Validator is activated from Source imports.
 Installing a new author package therefore does not require a video CLI or Core release. Source
@@ -67,9 +67,35 @@ to the chosen file. `measure` estimates a passage locally:
 
 ```bash
 hypit transcribe reference.mp4 --to notes/reference.transcript.json --language en
+hypit transcribe assets/recorded-voice.wav --to notes/voice.transcript.json --language en
 hypit measure main.svml --segment hook --language en --pace normal --rounding round
 ```
 
+`snapshot` follows the same immediate invocation model for picture inspection. Prefer it for
+existing production states and motion sequences, keeping Studio for playback with sound and Builds
+for encoded delivery:
+
+```bash
+hypit snapshot --studio http://localhost:5191 --at-frame 240,255,269 --to evidence/states
+hypit snapshot --studio http://localhost:5191 --start-frame 240 --end-frame-exclusive 270 \
+  --grid 4x3 --cell 480 --to evidence/motion
+hypit snapshot ./picture/index.html --at-frame 240 --to evidence/detail
+```
+
+`--studio` reads Studio's current compiled document and its declared resources; a path or HTML URL
+reads materialized HTML with inline scripts/styles and directly addressed media/fonts. The Profile's
+`@hypit/render-hyperframes@1#render-frames` Endpoint returns PNGs in selected-frame order.
+`--runtime` and `--workspace` select the environment just as for `transcribe`. The call streams
+resources through a temporary `FileResourceStore`, writes full-size PNGs and optional grid pages,
+then releases that temporary storage. `--to` names a new directory. `--json` reports paths and original
+frame positions. Grid labels remain outside the picture. No Build, Worker receipt or video encoding
+is created. Provider-owned browser preparation is unchanged.
+
+`media frames --every-frame` and `media tiles --every-frame` decode every source frame in a selected
+half-open seconds interval once. Native timestamps, including variable frame rate, are read from
+decoder PTS and time base. `tiles --ranges <json> --every-frame` decodes each listed interval and
+paginates its images. `--transcript` adds word context. This native path uses no FPS resampling.
+
 For `transcribe`, set `--language` to an explicit lowercase two- or three-letter spoken language code,
 such as `en`, `zh` or `ko`. The selected service owns which languages it can align. Chinese speech uses `zh`, including
 Chinese speech containing English names. The request selects the recognition language and
@@ -106,6 +132,9 @@ prints what a Source may write:
 ```bash
 hypit media probe reference.mp4
 hypit media cut reference.mp4 --start 12 --end 19.5 --label-time --to notes/hook.mp4
+hypit media cut assets/talk.mp4 --start 12 --end 19.5 --to assets/opening.mp4
+hypit media cut assets/talk.mp4 --keep 12:15.5 --keep 16:19.5 --to assets/opening-edited.mp4
+hypit media cut assets/narration.wav --keep 0.3:4.1 --keep 4.6:9.2 --to assets/narration-edited.wav
 hypit media frames reference.mp4 --at 12.4,13.1 --label-time --to notes/hook-frames
 hypit media tile reference.mp4 --start 12 --end 19.5 --to notes/hook-grid.jpg
 hypit media tile reference.mp4 --at 12.4,13.1,14.8 --columns 3 --to notes/exact-grid.jpg
@@ -119,7 +148,21 @@ hypit vocabulary @hypit/media-pipeline --tag StillVideo
 hypit vocabulary --visual text
 ```
 
-`cut` isolates the requested interval and can visibly overlay source time on the evidence copy.
+`probe` accepts audio-only files as well as video. `cut` keeps one interval using `--start` and
+`--end`, or joins explicitly retained, ordered, non-overlapping intervals using repeated
+`--keep start:end` in source seconds. The latter is useful for removing gaps inside one recorded
+performance; it does not decide where Script Segments belong. Video retains its available picture
+and sound together (MP4 is a useful output container); audio-only outputs PCM WAV. A silent source
+video stays silent. The
+`--json` reports the source intervals, their nominal positions on the new local clock, and the
+measured output duration; actual frame and sample boundaries can differ slightly from the nominal
+positions. It writes a new file and refuses to
+overwrite an existing one. `--label-time` retains its single-video-interval role: it visibly
+overlays source time on an inspection copy, not on the clean production media.
+
+`transcribe` also accepts audio or video. Its transcript refers to the *input file's* clock. A
+cut or joined file has a new clock; use the final recorded performance and its Script in the
+Build's semantic preparation rather than treating source transcript timestamps as final timing.
 `frames` writes one JPEG per requested time, selecting the first decoded frame at or after it.
 Visible frame labels use that frame's actual timestamp, as do the labels below each `tile` cell.
 Sampling is shared by `frames`, `tile` and `tiles`:
@@ -149,7 +192,7 @@ and its Endpoint remain separate. `boundaries` reports adjacent-frame
 change candidates and their measured scores; it does not suppress short changes or call them shots.
 `prepare-fetch` explicitly prepares the locked downloader environment; `fetch` requires it and
 turns a link into a file with the pinned yt-dlp; [the downloader package](../yt-dlp/README.md)
-owns its dependencies, download choices and file handling. Commands that create evidence write only
+owns its dependencies, download choices and file handling. Commands that create files write only
 what `--to` names and refuse to overwrite. `vocabulary` reads the installed
 manifests: every package with its tags and models, or one package's Surfaces with their attributes,
 children and example, or the value shapes a drawing Producer must emit.

package/packages/video-cli/package.json

@@ -18,6 +18,7 @@
     "@hypit/driver-node": "workspace:*",
     "@hypit/estimate": "workspace:*",
     "@hypit/generation": "workspace:*",
+    "@hypit/hyperframes": "workspace:*",
     "@hypit/markup": "workspace:*",
     "@hypit/model-kit": "workspace:*",
     "@hypit/package-loader-node": "workspace:*",
@@ -28,6 +29,8 @@
     "@hypit/provider-monid": "workspace:*",
     "@hypit/provider-pollo": "workspace:*",
     "@hypit/provider-tokendance": "workspace:*",
+    "@hypit/render-hyperframes": "workspace:*",
+    "@hypit/resource-store-fs": "workspace:*",
     "@hypit/runtime": "workspace:*",
     "@hypit/runtime-kit": "workspace:*",
     "@hypit/runtime-host-node": "workspace:*",

package/packages/video-cli/src/cli.ts

@@ -4,8 +4,10 @@ import type { CliIo } from "@hypit/cli";
 import { creationCommands, isCreationCommand, writeCreationHelp } from "./creation.js";
 import { isMediaCommand, mediaCommands, writeMediaHelp } from "./media.js";
 import { writeVocabularyHelp } from "./vocabulary.js";
+import { writeSnapshotHelp } from "./snapshot.js";
 import { writeCaptureHelp } from "./capture.js";
 import { runVersionCli, writeVersionHelp } from "./version.js";
+import { acceptSecretBytes } from "./secret-input.js";
 
 const argv = process.argv.slice(2);
 const json = argv.includes("--json");
@@ -26,22 +28,19 @@ async function readSecret(prompt: string): Promise<string> {
   }
   process.stderr.write(prompt);
   return await new Promise<string>((resolve, reject) => {
-    let value = "";
+    const raw: number[] = [];
     const finish = (error?: Error): void => {
       process.stdin.off("data", input);
       process.stdin.setRawMode(false);
       process.stdin.pause();
       process.stderr.write("\n");
-      if (error === undefined) resolve(value);
+      if (error === undefined) resolve(Buffer.from(raw).toString("utf8"));
       else reject(error);
     };
     const input = (chunk: Buffer): void => {
-      for (const byte of chunk) {
-        if (byte === 3) { finish(new Error("credential input cancelled")); return; }
-        if (byte === 10 || byte === 13) { finish(); return; }
-        if (byte === 8 || byte === 127) { value = value.slice(0, -1); continue; }
-        value += String.fromCharCode(byte);
-      }
+      const result = acceptSecretBytes(raw, chunk);
+      if (result === "cancelled") finish(new Error("credential input cancelled"));
+      if (result === "done") finish();
     };
     process.stdin.setRawMode(true);
     process.stdin.resume();
@@ -68,6 +67,7 @@ async function main(): Promise<void> {
     const topic = argv[0] === "help" ? argv[1]
       : argv[0] === "--help" ? undefined
       : argv.includes("--help") ? argv[0] : undefined;
+    if (topic === "snapshot") { writeSnapshotHelp(io); return; }
     if (topic === "version") { writeVersionHelp(io); return; }
     if (isCreationCommand(topic)) {
       writeCreationHelp(io, topic);
@@ -89,7 +89,7 @@ async function main(): Promise<void> {
     writeCliHelp(io, topic);
     if (topic === undefined) {
       io.write(`\nInstallation\n  version [--check] [--registry <url>] [--json]\n\nCreation tools (one request through the selected Runtime Profile, no Build)\n${
-        creationCommands.map((item) => `  ${item}`).join("\n")}\n  hypit help <tool> for each\n`
+        [...creationCommands, "snapshot"].map((item) => `  ${item}`).join("\n")}\n  hypit help <tool> for each\n`
         + `\nStudio\n  studio --run <build.svrun>\n  hypit studio --help for session options\n\nPreparation (local tools and project files)\n  media ${mediaCommands.join(" | ")}\n  capture screenshot | run | install-browser\n  vocabulary\n  hypit help media, hypit help capture, hypit help vocabulary\n`);
     }
     return;

package/packages/video-cli/src/creation.ts

@@ -150,7 +150,7 @@ function capabilityName(capability: CapabilityRef): string {
 }
 
 /** Which Endpoint will serve this call and where its Provider publishes prices, before spending. */
-async function selectedProvider(host: CreationHost, need: Need, profile: string): Promise<RuntimeHostCapabilityProvider> {
+export async function selectedProvider(host: CreationHost, need: Need, profile: string): Promise<RuntimeHostCapabilityProvider> {
   const [provider] = await host.providers([{
     request: need.id,
     capability: need.capability,
@@ -176,7 +176,7 @@ function priceLine(provider: RuntimeHostCapabilityProvider): string {
     : provider.pricing.kind === "local" ? "local, no Provider charge" : provider.pricing.url;
 }
 
-function providerView(provider: RuntimeHostCapabilityProvider) {
+export function providerView(provider: RuntimeHostCapabilityProvider) {
   return {
     endpoint: provider.endpoint ?? null,
     use: provider.use ?? null,
@@ -184,7 +184,7 @@ function providerView(provider: RuntimeHostCapabilityProvider) {
   };
 }
 
-function providerLine(provider: RuntimeHostCapabilityProvider): string {
+export function providerLine(provider: RuntimeHostCapabilityProvider): string {
   return `${provider.endpoint} (${provider.use})  ·  ${priceLine(provider)}`;
 }
 

package/packages/video-cli/src/frame-grid.ts

@@ -0,0 +1,34 @@
+import sharp from "sharp";
+
+/** Arrange already captured evidence. Decoding and time selection belong to the caller. */
+export async function writeFrameGrid(
+  frames: readonly { readonly path: string; readonly label: Buffer }[],
+  target: string, cellWidth: number, columns: number,
+): Promise<void> {
+  if (frames.length === 0) throw new Error("A frame grid needs at least one image");
+  const cells = [];
+  for (const frame of frames) {
+    const picture = await sharp(frame.path).resize({ width: cellWidth }).png().toBuffer({ resolveWithObject: true });
+    const labelHeight = (await sharp(frame.label).metadata()).height!;
+    cells.push({ picture: picture.data, height: picture.info.height, label: frame.label, labelHeight });
+  }
+  const pictureHeight = Math.max(...cells.map(cell => cell.height));
+  const rowHeight = pictureHeight + Math.max(...cells.map(cell => cell.labelHeight));
+  const rows = Math.ceil(cells.length / columns);
+  await sharp({ create: {
+    width: columns * (cellWidth + 8) + 8, height: rows * (rowHeight + 8) + 8,
+    channels: 3, background: "#0c0c0c",
+  } }).composite(cells.flatMap((cell, index) => {
+    const left = 8 + index % columns * (cellWidth + 8);
+    const top = 8 + Math.floor(index / columns) * (rowHeight + 8);
+    return [{ input: cell.picture, left, top }, { input: cell.label, left, top: top + pictureHeight }];
+  })).toFile(target);
+}
+
+export async function snapshotFrameLabel(frame: number, seconds: number, width: number): Promise<Buffer> {
+  const text = await sharp({ text: { text: `<span foreground="#f5f5f5">Frame ${frame} · ${seconds.toFixed(6)} s</span>`,
+    font: `sans ${Math.max(12, Math.round(width / 28))}`, width: width - 16, rgba: true,
+  } }).png().toBuffer({ resolveWithObject: true });
+  return sharp({ create: { width, height: text.info.height + 16, channels: 3, background: "#0c0c0c" } })
+    .composite([{ input: text.data, left: 8, top: 8 }]).png().toBuffer();
+}

package/packages/video-cli/src/index.ts

@@ -12,6 +12,7 @@ import { videoCliDistribution } from "./distribution.js";
 import { runMediaCli } from "./media.js";
 import { runVocabularyCli } from "./vocabulary.js";
 import { runCaptureCli } from "./capture.js";
+import { runSnapshotCli } from "./snapshot.js";
 import { runVersionCli } from "./version.js";
 
 export {
@@ -42,6 +43,7 @@ export function runVideoCli(
     : [videoCliDistribution.packageRoot]);
   installExternalPackageResolution([hypitHostPackageRoot()]);
   if (isCreationCommand(argv[0])) return runCreationCli(argv, io);
+  if (argv[0] === "snapshot") return runSnapshotCli(argv, io);
   if (argv[0] === "media") return runMediaCli(argv, io);
   if (argv[0] === "capture") return runCaptureCli(argv, io);
   if (argv[0] === "vocabulary") return runVocabularyCli(argv, io);
@@ -50,3 +52,5 @@ export function runVideoCli(
     bootstrapPackages: packages,
   });
 }
+
+export { runSnapshotCli, writeSnapshotHelp } from "./snapshot.js";