@hypit/hypit 0.2.6 → 0.2.8

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";

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

@@ -0,0 +1,25 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { runProcessOutput } from "./process.js";
+
+export type DecodedFrame = { readonly at: number; readonly path: string };
+
+/** Decode a source interval once, retaining each decoded frame and its actual source timestamp. */
+export async function decodeMediaFrames(source: string, start: number, end: number, directory: string): Promise<readonly DecodedFrame[]> {
+  if (!Number.isFinite(start) || start < 0 || !Number.isFinite(end) || end <= start) throw new Error("Native frames need 0 <= start < end");
+  await mkdir(directory, { recursive: true });
+  const times: number[] = [];
+  let numerator = 0, denominator = 0;
+  await runProcessOutput("ffmpeg", ["-hide_banner", "-loglevel", "info", "-nostdin", "-copyts", "-start_at_zero",
+    ...(start > 0 ? ["-ss", String(start)] : []), "-i", source,
+    "-map", "0:v:0", "-an", "-vf", `trim=start=${start}:end=${end},showinfo=checksum=0`,
+    "-fps_mode", "passthrough", "-pix_fmt", "yuvj420p", "-q:v", "3", "-start_number", "0", join(directory, "%09d.jpg"),
+  ], 300_000, line => {
+    const base = /config in time_base:\s*(\d+)\/(\d+)/u.exec(line);
+    if (base !== null) { numerator = Number(base[1]); denominator = Number(base[2]); }
+    const pts = /\bn:\s*\d+\s+pts:\s*(-?\d+)/u.exec(line);
+    if (pts !== null && denominator > 0) times.push(Number(pts[1]) * numerator / denominator);
+  });
+  if (times.length === 0) throw new Error(`No video frames in [${start}, ${end}) s`);
+  return times.map((at, index) => ({ at, path: join(directory, `${String(index).padStart(9, "0")}.jpg`) }));
+}