@hypit/hypit 0.1.14 → 0.2.0

package/packages/caption-fine/src/render.ts

@@ -8,19 +8,22 @@ import type {
   VisualColorPaint,
   VisualElement,
   VisualKeyframe,
+  VisualProgramElement,
   VisualStyleDeclaration,
   VisualTextElement,
   VisualTextPaintLayer,
   VisualTrack,
 } from "@hypit/composition";
-import type { CaptionAlignmentUnit, CaptionDocument } from "@hypit/narrative";
+import type { CaptionAlignmentUnit, CaptionDocument, CaptionDisplayWord } from "@hypit/narrative";
 import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
 import { assertSpatialRegionTimeline } from "@hypit/spatial";
 import type { CanvasSpace, SpatialFrame, SpatialRegionTimeline } from "@hypit/spatial";
 
 import { assertFineCaptionParameters, FINE_CAPTION_FAMILY } from "./style.js";
 import { assertFineCaptionSchedule } from "./schedule.js";
-import { joinSurfaces, uniformGap, wordGapBetween, wordGaps } from "./spacing.js";
+import { uniformGap, wordGaps } from "./spacing.js";
+import { browserProgram } from "@hypit/hyperframes";
+import { joinedBoxSetup } from "./joined-box.js";
 import type {
   FineCaptionActiveUnderline,
   FineCaptionGlyphPaint,
@@ -621,20 +624,17 @@ function trackedPlacementAnimation(
   return { keyframes };
 }
 
-function structuralRowCount(
-  atoms: readonly CaptionAlignmentUnit[],
-  maxWordsPerLine: number,
-): number {
-  let rows = atoms.length === 0 ? 0 : 1;
+function structuralRowStarts(atoms: readonly CaptionAlignmentUnit[], maxWordsPerLine?: number): ReadonlySet<number> {
+  const starts = new Set<number>();
   let wordsOnRow = 0;
-  for (const atom of atoms) {
-    if (wordsOnRow > 0 && wordsOnRow + atom.wordIds.length > maxWordsPerLine) {
-      rows += 1;
+  for (const [index, atom] of atoms.entries()) {
+    if (index === 0 || (maxWordsPerLine !== undefined && wordsOnRow > 0 && wordsOnRow + atom.wordIds.length > maxWordsPerLine)) {
+      starts.add(index);
       wordsOnRow = 0;
     }
     wordsOnRow += atom.wordIds.length;
   }
-  return rows;
+  return starts;
 }
 
 /**
@@ -665,7 +665,7 @@ function cueElements(
   atoms: readonly CaptionAlignmentUnit[],
   atomFrames: ReadonlyMap<string, { readonly start: number; readonly end: number }>,
   parameters: FineCaptionParameters,
-  wordText: ReadonlyMap<string, string>,
+  wordText: ReadonlyMap<string, CaptionDisplayWord>,
   durationFrames: number,
   styleId: string,
   trackedPlacement?: {
@@ -673,7 +673,7 @@ function cueElements(
     readonly canvas: CanvasSpace;
   },
 ): VisualElement[] {
-  type UnorderedVisualElement = Omit<VisualBoxElement, "order"> | Omit<VisualTextElement, "order">;
+  type UnorderedVisualElement = Omit<VisualBoxElement, "order"> | Omit<VisualTextElement, "order"> | Omit<VisualProgramElement, "order">;
   const elements: VisualElement[] = [];
   let order = 0;
   const push = (element: UnorderedVisualElement): void => {
@@ -694,21 +694,29 @@ function cueElements(
   const cueLoop = parameters.motion.loopTarget === "cue" ? loopAnimation(parameters, durationFrames) : undefined;
   const activationFrames = exclusiveActivationFrames(atoms, atomFrames);
   const gapPx = `${compactNumber(parameters.layout.wordGapPx)}px`;
-  const atomSurfaces = atoms.map((atom) => atom.wordIds.map((wordId) => wordText.get(wordId) ?? ""));
-  // A Cue whose boundaries all agree carries one `column-gap`, which is also what keeps a row that
-  // wraps from opening on a margin. A Cue that mixes scripts spaces each element instead.
-  const atomGaps = atomSurfaces.map((surfaces, index) => {
-    const previous = atomSurfaces[index - 1];
-    return previous === undefined ? false : wordGapBetween(previous.at(-1) ?? "", surfaces[0] ?? "");
-  });
-  const cueGap = uniformGap(atomGaps);
+  const atomWords = atoms.map(atom => atom.wordIds.map(wordId => {
+    const word = wordText.get(wordId);
+    if (!word) throw new Error(`Fine Caption Atom references unknown word ${wordId}`);
+    return word;
+  }));
+  const atomSurfaces = atomWords.map(words => words.map(word => word.text));
+  const atomGaps = atomWords.map((words, index) => index > 0 && words[0]!.separatorBefore === " ");
   // The Visual IR carries physical margins, so the leading edge follows the Cue's own direction.
   const marginStart = parameters.layout.direction === "rtl" ? "margin-right" : "margin-left";
   const spacedStyle = (spaced: boolean): readonly VisualStyleDeclaration[] =>
     spaced ? [{ name: marginStart, value: gapPx }] : [];
+  const atomFlow = (words: readonly CaptionDisplayWord[]): VisualStyleDeclaration[] => [
+    ...(uniformGap(wordGaps(words)) === true ? [{ name: "column-gap", value: gapPx }] : []),
+    { name: "display", value: "inline-flex" },
+    { name: "min-width", value: "0" },
+    { name: "overflow-wrap", value: "anywhere" },
+    { name: "white-space", value: "normal" },
+    { name: "word-break", value: parameters.layout.wrap === "grapheme" ? "break-all" : "normal" },
+  ];
   const fonts = parameters.typography.exactFonts;
+  const rowStarts = structuralRowStarts(atoms, parameters.layout.maxWordsPerLine);
   if (parameters.layout.maxLines !== undefined) {
-    const rows = structuralRowCount(atoms, parameters.layout.maxWordsPerLine!);
+    const rows = rowStarts.size;
     if (rows > parameters.layout.maxLines) {
       throw new Error(`Fine Caption Style ${styleId} constructs ${rows} rows for a Cue whose maximum is ${parameters.layout.maxLines}`);
     }
@@ -766,10 +774,10 @@ function cueElements(
       { name: "border-radius", value: `${compactNumber(parameters.cueBox.radiusPx)}px` },
       { name: "border-style", value: "solid" },
       { name: "border-width", value: `${compactNumber(parameters.cueBox.borderWidthPx)}px` },
-      ...(cueGap === true ? [{ name: "column-gap", value: gapPx }] as const : []),
       { name: "direction", value: parameters.layout.direction },
-      { name: "display", value: "flex" },
-      { name: "flex-wrap", value: "wrap" },
+      { name: "display", value: "block" },
+      { name: "font-size", value: "0px" },
+      { name: "line-height", value: "0" },
       { name: "justify-content", value: parameters.layout.textAlign === "left" ? "flex-start"
         : parameters.layout.textAlign === "right" ? "flex-end" : "center" },
       { name: "max-width", value: "100%" },
@@ -781,64 +789,73 @@ function cueElements(
     ],
   });
 
+  const pushSeparator = (id: string, parent: string): void => push({
+    id, parent, kind: "text", text: " ", fonts,
+    style: [
+      { name: "display", value: "inline" },
+      { name: "font-size", value: "0px" },
+      { name: "letter-spacing", value: gapPx },
+      { name: "line-height", value: "0" },
+      { name: "white-space", value: "normal" },
+    ],
+  });
+
   if (parameters.activeBox.mode === "trail" && parameters.activeBox.continuity === "joined") {
-    for (const [prefixIndex, atom] of atoms.entries()) {
-      const timing = atomFrames.get(atom.id);
-      if (timing === undefined) throw new Error(`Fine Caption is missing timing for Atom ${atom.id}`);
-      const next = atoms[prefixIndex + 1];
+    // Fine owns this drawing program. The renderer only executes its existing browser-program
+    // format; it learns nothing about captions, activation units or their layout rules.
+    push({
+      id: "joined-boxes", parent: "cue", kind: "program",
+      style: [
+        { name: "position", value: "absolute" }, { name: "inset", value: "0" },
+        { name: "padding", value: `${compactNumber(parameters.cueBox.paddingYPx)}px ${compactNumber(parameters.cueBox.paddingXPx)}px` },
+      ],
+      program: browserProgram({
+        html: "{{joined-layout}}" + atoms.map((_, index) => `{{joined-box-${index + 1}}}`).join(""),
+        setup: joinedBoxSetup,
+        css: ":scope { pointer-events: none; }",
+        data: {
+          wordCounts: atomWords.map(words => words.length),
+          background: parameters.activeBox.background, borderColor: parameters.activeBox.borderColor,
+          borderWidth: parameters.activeBox.borderWidthPx, radius: parameters.activeBox.radiusPx,
+          paddingX: parameters.activeBox.paddingXPx, paddingY: parameters.activeBox.paddingYPx,
+        },
+      }),
+    });
+    push({ id: "joined-layout", parent: "joined-boxes", kind: "box",
+      style: [{ name: "visibility", value: "hidden" }],
+      attributes: [{ name: "data-fine-box-layout", value: "" }],
+    });
+    // The complete stationary Cue supplies layout, including the inactive suffix. Its actual
+    // word fragments determine the background; decoration contributes no width to text flow.
+    for (const [index, words] of atomWords.entries()) {
+      if (index > 0 && rowStarts.has(index)) push({ id: `joined-break-${index}`, parent: "joined-layout", kind: "box",
+        style: [{ name: "display", value: "block" }, { name: "height", value: "0" }],
+      });
+      if (!rowStarts.has(index) && words[0]!.separatorBefore === " ") pushSeparator(`joined-gap-${index}`, "joined-layout");
+      const groupId = `joined-group-${index}`;
+      push({ id: groupId, parent: "joined-layout", kind: "box", style: [...atomFlow(words), { name: "max-width", value: "100%" }] });
+      const gaps = wordGaps(words);
+      for (const [wordIndex, word] of words.entries()) {
+        push({ id: `${groupId}-word-${wordIndex}`, parent: groupId, kind: "text", text: word.text, fonts,
+          style: [...transparentGlyphStyle(parameters),
+            ...(uniformGap(gaps) === undefined ? spacedStyle(gaps[wordIndex] ?? false) : [])],
+          attributes: [{ name: "data-fine-box-word", value: "" }],
+        });
+      }
+    }
+    for (const [index, atom] of atoms.entries()) {
+      const timing = atomFrames.get(atom.id)!;
+      const next = atoms[index + 1];
       const nextStart = next === undefined ? durationFrames : atomFrames.get(next.id)?.start;
       if (nextStart === undefined) throw new Error("Fine Caption is missing timing for the next Atom");
-      // A no-break space inside an atom keeps its words on one row; the boundaries between atoms
-      // take an ordinary space. Both are spaced only where the surfaces meeting there call for one.
-      const prefixText = joinSurfaces(
-        atoms.slice(0, prefixIndex + 1).map((prefixAtom, index) => {
-          for (const wordId of prefixAtom.wordIds) {
-            if (!wordText.has(wordId)) throw new Error(`Fine Caption Atom references unknown word ${wordId}`);
-          }
-          return joinSurfaces(atomSurfaces[index] ?? [], "\u00A0");
-        }),
-        " ",
-      );
-      const layerId = `joined-box-${prefixIndex + 1}`;
-      push({
-        id: layerId,
-        parent: "cue",
-        kind: "box",
-        style: [
-          { name: "box-sizing", value: "border-box" },
-          { name: "direction", value: parameters.layout.direction },
-          { name: "inset", value: "0" },
-          { name: "padding", value: `${compactNumber(parameters.cueBox.paddingYPx)}px ${compactNumber(parameters.cueBox.paddingXPx)}px` },
-          { name: "position", value: "absolute" },
-          { name: "text-align", value: parameters.layout.textAlign },
-        ],
+      push({ id: `joined-box-${index + 1}`, parent: "joined-boxes", kind: "box",
+        style: [{ name: "position", value: "absolute" }, { name: "inset", value: "0" }],
         animation: activeBoxAnimation(parameters, timing.start, nextStart, durationFrames, "current"),
         attributes: [{ name: "data-caption-active-box", value: "joined" }],
       });
-      push({
-        id: `${layerId}-text`,
-        parent: layerId,
-        kind: "text",
-        text: prefixText,
-        style: [
-          ...transparentGlyphStyle(parameters).filter(({ name }) => name !== "white-space"),
-          { name: "-webkit-box-decoration-break", value: "clone" },
-          { name: "background", value: parameters.activeBox.background },
-          { name: "border-color", value: parameters.activeBox.borderColor },
-          { name: "border-radius", value: `${compactNumber(parameters.activeBox.radiusPx)}px` },
-          { name: "border-style", value: "solid" },
-          { name: "border-width", value: `${compactNumber(parameters.activeBox.borderWidthPx)}px` },
-          { name: "box-decoration-break", value: "clone" },
-          { name: "display", value: "inline" },
-          { name: "padding", value: `${compactNumber(parameters.activeBox.paddingYPx)}px ${compactNumber(parameters.activeBox.paddingXPx)}px` },
-          { name: "white-space", value: "normal" },
-        ],
-        fonts,
-      });
     }
   }
 
-  let wordsOnLine = 0;
   for (const [atomIndex, atom] of atoms.entries()) {
     const timing = atomFrames.get(atom.id);
     if (timing === undefined) throw new Error(`Fine Caption is missing timing for Atom ${atom.id}`);
@@ -848,22 +865,20 @@ function cueElements(
     const surfaces = atomSurfaces[atomIndex] ?? [];
     // The base glyphs and the activated copy stacked over them are laid out from this one list, so
     // the karaoke wipe keeps sitting on the letterforms it reveals.
-    const gaps = wordGaps(surfaces);
+    const gaps = wordGaps(atomWords[atomIndex]!);
     const wordGap = uniformGap(gaps);
     const entryId = `${atomId}-entry`;
     const loopId = `${atomId}-loop`;
     const responseId = `${atomId}-response`;
-    if (parameters.layout.maxWordsPerLine !== undefined
-      && wordsOnLine > 0
-      && wordsOnLine + atom.wordIds.length > parameters.layout.maxWordsPerLine) {
+    if (atomIndex > 0 && rowStarts.has(atomIndex)) {
       push({
         id: `line-break-${atomIndex}`,
         parent: "cue",
         kind: "box",
-        style: [{ name: "flex-basis", value: "100%" }, { name: "height", value: "0" }],
+        style: [{ name: "display", value: "block" }, { name: "height", value: "0" }],
       });
-      wordsOnLine = 0;
     }
+    if (!rowStarts.has(atomIndex) && atomGaps[atomIndex]) pushSeparator(`gap-${atomIndex}`, "cue");
     const entryAnimation = atomLifecycleAnimation(parameters, timing.start, timing.end, durationFrames);
     const atomLoop = parameters.motion.loopTarget === "active-atom"
       ? loopAnimation(parameters, durationFrames, activationTiming) : undefined;
@@ -880,8 +895,6 @@ function cueElements(
       style: [
         { name: "display", value: "inline-flex" },
         { name: "min-width", value: "0" },
-        // A row that wraps opens at its own edge, so an atom that starts one carries no margin.
-        ...(cueGap === undefined && wordsOnLine > 0 ? spacedStyle(atomGaps[atomIndex] ?? false) : []),
         { name: "transform-origin", value: "center center" },
       ],
       ...(entryAnimation === undefined ? {} : { animation: entryAnimation }),
@@ -913,13 +926,8 @@ function cueElements(
       parent: responseId,
       kind: "box",
       style: [
-        ...(wordGap === true ? [{ name: "column-gap", value: gapPx }] as const : []),
-        { name: "display", value: "inline-flex" },
-        { name: "min-width", value: "0" },
-        { name: "overflow-wrap", value: "anywhere" },
+        ...atomFlow(atomWords[atomIndex]!),
         { name: "position", value: "relative" },
-        { name: "white-space", value: "normal" },
-        { name: "word-break", value: parameters.layout.wrap === "grapheme" ? "break-all" : "normal" },
       ],
       attributes: [{ name: "data-caption-atom", value: atom.id }],
     });
@@ -996,7 +1004,7 @@ function cueElements(
       }
     };
     for (const [wordIndex, wordId] of atom.wordIds.entries()) {
-      const text = wordText.get(wordId);
+      const text = wordText.get(wordId)?.text;
       if (text === undefined) throw new Error(`Fine Caption Atom references unknown word ${wordId}`);
       pushText({
         id: `${atomId}-base-${wordIndex + 1}`,
@@ -1037,7 +1045,7 @@ function cueElements(
         attributes: [{ name: kind === "glyph" ? "data-caption-karaoke" : "data-caption-active-underline", value: mode }],
       });
       for (const [wordIndex, wordId] of atom.wordIds.entries()) {
-        const text = wordText.get(wordId)!;
+        const text = wordText.get(wordId)!.text;
         pushText({
           id: `${activeId}-${wordIndex + 1}`,
           parent: activeId,
@@ -1060,7 +1068,6 @@ function cueElements(
     if (parameters.activeUnderline.mode !== "off") {
       addActivatedTextLayer("underline", parameters.activeUnderline.mode, "underline");
     }
-    wordsOnLine += atom.wordIds.length;
   }
   return elements;
 }
@@ -1081,7 +1088,7 @@ export function renderFineCaption(
     throw new Error("Fine Caption inputs belong to different Timelines or Narratives");
   }
   const styles = new Map(program.styles.map((style) => [style.id, style]));
-  const wordText = new Map(document.words.map((word) => [word.id, word.text]));
+  const wordText = new Map(document.words.map((word) => [word.id, word]));
   const atomById = new Map(document.units.map((atom) => [atom.id, atom]));
   for (const style of styles.values()) {
     if (style.rendering === null) continue;

package/packages/caption-fine/src/spacing.ts

@@ -1,69 +1,16 @@
-/**
- * Where a word gap belongs between two adjacent display surfaces.
- *
- * A Display Word is one lexical unit, and in Han, Hiragana and Katakana that unit is a single
- * character. A gap applied to every boundary therefore sets Chinese and Japanese as though every
- * character were a word, so each boundary decides its own gap from the two characters that meet
- * across it.
- *
- * The classes follow pangu.js: a CJK character beside a half-width letter, digit, bracket or
- * operator takes one space. The gap pangu inserts is an ordinary space, so a boundary either
- * carries the Style's `word-gap` or carries nothing.
- */
+import type { CaptionDisplayWord } from "@hypit/narrative";
 
-/** The three scripts the Script tokenizer treats as one character per lexical unit. */
-const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/u;
+type Surface = Pick<CaptionDisplayWord, "text" | "separatorBefore">;
 
-/**
- * Full-width punctuation, including the bracket, quotation and dash pairs.
- *
- * These glyphs are drawn inside a full-width em box with their own side bearing, so a gap beside
- * one paints a second space over the one the font already carries. The ranges cover CJK
- * punctuation, the full-width ASCII forms, the curly quotes and the ellipsis, and stop short of
- * the full-width digits and letters at `０-９`, `Ａ-Ｚ` and `ａ-ｚ`, which
- * are ordinary word characters.
- */
-const FULL_WIDTH_PUNCTUATION =
-  /[、-〃〈-】〔-〟！-／：-＠［-｀｛-･‘’“”—…]/u;
-
-/**
- * Half-width brackets and quotation marks take their space on the outside of the pair, which falls
- * out of reading the boundary characters: `displayWordSurfaces` attaches an opener to the surface
- * that follows it and a closer to the surface before it, so `中文(注)中文` meets `(` on the right
- * of one boundary and `)` on the left of the next, and both take a gap.
- *
- * A boundary with no CJK character on either side keeps the gap it has today. Latin spacing is not
- * what this decides.
- */
-export function wordGapBetween(previous: string, next: string): boolean {
-  const left = [...previous].at(-1);
-  const right = [...next].at(0);
-  if (left === undefined || right === undefined) return false;
-  if (FULL_WIDTH_PUNCTUATION.test(left) || FULL_WIDTH_PUNCTUATION.test(right)) return false;
-  return !(CJK.test(left) && CJK.test(right));
-}
-
-/** Every boundary in order. The first surface opens the run, so its entry is always `false`. */
-export function wordGaps(surfaces: readonly string[]): readonly boolean[] {
-  return surfaces.map((surface, index) => {
-    const previous = surfaces[index - 1];
-    return previous === undefined ? false : wordGapBetween(previous, surface);
-  });
+/** The first displayed word starts a line; all other gaps come from authored content. */
+export function wordGaps(words: readonly Surface[]): readonly boolean[] {
+  return words.map((word, index) => index > 0 && word.separatorBefore === " ");
 }
 
-/**
- * A run whose boundaries all agree carries one `column-gap` on its container. A mixed run cannot,
- * because `column-gap` is uniform, and takes a margin per element instead.
- */
+/** A uniform run can use column-gap; a mixed run requires individual separators. */
 export function uniformGap(gaps: readonly boolean[]): boolean | undefined {
   const boundaries = gaps.slice(1);
   if (boundaries.length === 0) return false;
-  if (boundaries.every((gap) => gap)) return true;
-  return boundaries.some((gap) => gap) ? undefined : false;
-}
-
-/** Join surfaces back into prose, spacing only the boundaries that carry a gap. */
-export function joinSurfaces(surfaces: readonly string[], separator: string): string {
-  const gaps = wordGaps(surfaces);
-  return surfaces.map((surface, index) => (gaps[index] ? `${separator}${surface}` : surface)).join("");
+  if (boundaries.every(gap => gap)) return true;
+  return boundaries.some(gap => gap) ? undefined : false;
 }

package/packages/caption-fine-studio/src/index.ts

@@ -114,10 +114,8 @@ function cueText(document: CaptionDocument | undefined, unitIds: readonly string
   const selected = new Set(unitIds);
   return document.words
     .filter((word) => selected.has(word.unitId))
-    .map((word) => word.text)
-    .join(" ")
-    .replace(/([\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}])\s+(?=[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}])/gu, "$1")
-    .trim();
+    .map((word, index) => (index === 0 ? "" : word.separatorBefore) + word.text)
+    .join("");
 }
 
 export function projectCaptionContents(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {

package/packages/cli/README.md

@@ -153,13 +153,14 @@ paths. A deleted Source or directory remains queryable: only its existing ancest
 the missing path suffix is retained. This is local argument handling, with no saved alias inventory.
 CLI, Studio and creation tools call that same package; the CLI is not another environment owner.
 
-`doctor`, `programs up|status|down`, and `runtime up` accept repeated `--endpoint <instance>` values.
+`doctor`, `programs prepare|up|status|down`, and `runtime up` accept repeated `--endpoint <instance>` values.
 The same Endpoint scope reaches package preparation and Program operations. Omission means the whole
 Profile. Build preflight instead uses the Endpoints resolved for that Build's concrete requests.
 An unrelated offered capability does not add another credential or Program requirement.
 Program rows show the configured Endpoint selector alongside an internal Program ID when they differ.
 The `programs` JSON `ok` field reports whether this command succeeded; `ready` reports service
-readiness. Successful stopping can therefore report `ok: true` with `ready: false`. A declined stop remains visible even
+readiness for `up`/`status`, and preparation readiness for `prepare`. The latter does not start the
+service. Successful stopping can therefore report `ok: true` with `ready: false`. A declined stop remains visible even
 while the service is still preparing and cannot yet answer its health probe.
 
 Upstream package installation reports an `install.log` path at preparation time. Exact package

package/packages/cli/src/arguments.ts

@@ -349,8 +349,8 @@ function parseRuntimeCommand(tail: readonly string[]): RuntimeSelectionCommand |
 
 function parseProgramsCommand(tail: readonly string[]): ProgramsCommand {
   const [action, ...values] = tail;
-  if (action !== "up" && action !== "down" && action !== "status") {
-    throw new Error("programs takes up, down or status");
+  if (action !== "prepare" && action !== "up" && action !== "down" && action !== "status") {
+    throw new Error("programs takes prepare, up, down or status");
   }
   const [profile, rest] = optionalPositional(values);
   const options = commandOptions(`programs ${action}`, rest,

package/packages/cli/src/command.ts

@@ -146,7 +146,7 @@ export type ProgramsCommand =
   | (CommandBase & RuntimeOption & {
       readonly command: "programs";
       readonly endpoints?: readonly string[];
-      readonly action: "down" | "status";
+      readonly action: "prepare" | "down" | "status";
       readonly limit: number;
     });
 

package/packages/cli/src/commands/environment.ts

@@ -175,7 +175,7 @@ export async function runEnvironmentCommand(input: {
     if (runtimeProfile === undefined) throw new Error("programs requires a Runtime Profile");
     const profile = resolve(runtimeProfile);
     const host = await runtimeHost(profile);
-    if (args.action === "up") {
+    if (args.action === "up" || args.action === "prepare") {
       await host.prepare({ ...(args.endpoints === undefined ? {} : { endpoints: args.endpoints }), ...(reportPackageProgress === undefined ? {} : { onProgress: reportPackageProgress }) });
     }
     const controller = await runtimeController(profile);
@@ -185,6 +185,11 @@ export async function runEnvironmentCommand(input: {
         ...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
         ...(reportProgramProgress === undefined ? {} : { onProgress: reportProgramProgress }),
       })
+      : args.action === "prepare"
+        ? await controller.programs.prepare({
+          ...(args.endpoints === undefined ? {} : { endpoints: args.endpoints }),
+          ...(reportProgramProgress === undefined ? {} : { onProgress: reportProgramProgress }),
+        })
       : args.action === "down"
         ? await controller.programs.down(args.endpoints === undefined ? {} : { endpoints: args.endpoints })
         : await controller.programs.report(args.endpoints === undefined ? {} : { endpoints: args.endpoints });
@@ -199,7 +204,9 @@ export async function runEnvironmentCommand(input: {
     const urgent = relevant.filter(needsAttention);
     const shownPrograms = [...urgent, ...relevant.filter((item) => !needsAttention(item)).slice(0, Math.max(0, args.limit - urgent.length))];
     const omittedPrograms = relevant.length - shownPrograms.length;
-    const title = args.action === "up"
+    const title = args.action === "prepare"
+      ? lifecycleOk ? "External program resources prepared" : "External program preparation needs attention"
+      : args.action === "up"
       ? lifecycleOk ? "External programs ready" : "External programs need attention"
       : args.action === "down"
         ? lifecycleOk ? "External programs stopped" : "External program stop needs attention"

package/packages/cli/src/machine-view.ts

@@ -20,7 +20,7 @@ export type OperationalMachineView =
   | { readonly format: "hypit.cli-runtime-selection@1"; readonly selected: boolean; readonly removed?: boolean; readonly profile?: string; readonly project?: string }
   | { readonly format: "hypit.cli-paths@1"; readonly project: string; readonly projectState: string; readonly profileSource: "argument" | "project" | "none"; readonly selectionFile: string; readonly profile?: string; readonly runtimeData?: string; readonly hostState: string; readonly machinePackages: string; readonly distribution?: string }
   | { readonly format: "hypit.cli-package@1"; readonly action: "install" | "status"; readonly package: string; readonly ready: boolean }
-  | { readonly format: "hypit.cli-programs@1"; readonly action: "up" | "down" | "status"; readonly ok: boolean; readonly ready: boolean; readonly programCount: number; readonly readyCount: number; readonly programs: readonly ProgramStateView[]; readonly omittedPrograms?: number }
+  | { readonly format: "hypit.cli-programs@1"; readonly action: "prepare" | "up" | "down" | "status"; readonly ok: boolean; readonly ready: boolean; readonly programCount: number; readonly readyCount: number; readonly programs: readonly ProgramStateView[]; readonly omittedPrograms?: number }
   | { readonly format: "hypit.cli-runtime-up@1"; readonly ready: boolean; readonly worker: string; readonly preparedPackages: number; readonly programs: { readonly total: number; readonly ready: number; readonly items: readonly ProgramStateView[] } }
   | { readonly format: "hypit.cli-runtime-logs@1"; readonly lines: readonly string[]; readonly totalLines: number; readonly omittedLines: number; readonly path?: string }
   | { readonly format: "hypit.cli-runtime-down@1"; readonly worker: string }

package/packages/cli/src/output.ts

@@ -878,6 +878,7 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
       colors.accent(colors.strong("hypit programs")),
       colors.dim("Prepare and operate external programs declared by Endpoints in one Runtime Profile."),
       "",
+      "  hypit programs prepare [--runtime <profile>] [--endpoint <instance>]  # resources only; does not start services",
       "  hypit programs up [--runtime <profile>] [--workspace <project>] [--max-wait-ms <ms>]",
       "  hypit programs status [--runtime <profile>] [--workspace <project>]",
       "  hypit programs down [--runtime <profile>] [--workspace <project>]",

package/packages/credential-store-os/src/store.ts

@@ -141,7 +141,11 @@ function platformBackend(service: string) {
     return { read: macosReader(service), write: macosWriter(service), remove: macosDeleter(service) };
   }
   if (process.platform === "win32") return windowsBackend();
-  throw new Error("OS CredentialStore supports macOS and Windows only");
+  // A Profile that selects this Store cannot be repaired by anything the user does here, and the
+  // other two Stores are the answer, so name them where the failure is read.
+  throw new Error("OS CredentialStore supports macOS and Windows only; select "
+    + "@hypit/credential-store-file (owner-private local file) or @hypit/credential-store-env "
+    + "(externally supplied value) in this Profile's credentials instead");
 }
 
 /** One logical writable store backed by the current user's OS credential locker. */

package/packages/narrative/README.md

@@ -26,4 +26,6 @@ no Tokens. Authored order is independent of gaps, overlap or placement order in
 Caption uses this content query and the Narrative's display correspondence to select complete
 subtitle units. Timeline projection uses the same semantic references to locate events in physical
 time. Neither operation substitutes for the other. Token lookup returns Tokens, not reconstructed
-source prose: whitespace, comments and source-preserving edits remain the author language's concern.
+source prose: comments and source-preserving edits remain the author language's concern. Caption
+Display Words separately carry `separatorBefore` (`""` or `" "`) so consumers can reconstruct the
+authored display spelling without guessing from Token boundaries or importing an author parser.

package/packages/narrative/src/schema.ts

@@ -29,6 +29,7 @@ export const narrativeExcerptSchema: ValueSchema = object({
   tokenStart: { schema: integer }, tokenEndExclusive: { schema: integer },
 });
 const captionDisplayWord = object({
+  separatorBefore: { schema: { kind: "string", enum: ["", " "] } },
   id: { schema: string }, unitId: { schema: string }, segmentId: { schema: string },
   turnId: { schema: string }, role: { schema: string, optional: true }, text: { schema: string },
   attributes: { schema: { kind: "array", items: object({

package/packages/narrative/src/types.ts

@@ -50,6 +50,8 @@ export type NarrativeMomentRef = NarrativeMoment & {
 
 /** One author-visible word surface. Punctuation owned by the surface is preserved. */
 export type CaptionDisplayWord = {
+  /** Authored display separator from the preceding word; ignored at a displayed line start. */
+  readonly separatorBefore: "" | " ";
   readonly id: string;
   readonly unitId: string;
   readonly segmentId: string;

package/packages/provider-whisperx-local/README.md

@@ -43,7 +43,8 @@ For multilingual transcription with quality as the priority and suitable hardwar
     "expectedModel": "large-v3",
     "expectedDevice": "cuda",
     "expectedCompute": "float16",
-    "expectedBatchSize": 4
+    "expectedBatchSize": 4,
+    "alignmentLanguages": ["zh", "en"]
   }
 }
 ```
@@ -57,7 +58,11 @@ or hosted service for the actual language, material and time available rather th
 successively larger models as a routine sequence.
 
 `expectedModel` selects speech recognition. WhisperX separately loads the language-specific
-alignment model when that language is first requested. A larger ASR model can improve the words
+alignment model from prepared local resources when that language is first requested. Set
+`alignmentLanguages` to the language codes needed by this production before preparation. This is a
+preparation demand, not a central language whitelist; already cached supported languages remain usable.
+Omission prepares only ASR and sentence data, and does not imply every alignment model is installed.
+A larger ASR model can improve the words
 fed into alignment, but does not select a larger aligner or guarantee better timing by itself.
 The health response identifies the loaded ASR configuration; it does not establish that every
 language's alignment weights are cached. See [WhisperX usage](https://github.com/m-bain/whisperX#usage-)
@@ -65,8 +70,9 @@ and [faster-whisper deployment](https://github.com/SYSTRAN/faster-whisper#usage)
 
 ## Preparation and downloads
 
-The Runtime installs and starts the packaged service in the machine Program Home when this Endpoint
-is selected. The environment is reused across projects and sessions. The current local package and
+An explicit `programs up` or `runtime up` prepares and starts the selected packaged service in the
+machine Program Home. Selecting an Endpoint alone does not install it. The environment is reused
+across projects and sessions. The current local package and
 service are trusted code; this is not a community-plugin sandbox.
 
 `hypit paths` reports the machine `hostState`. The managed installation lives below
@@ -75,21 +81,31 @@ service are trusted code; this is not a community-plugin sandbox.
 the service host includes its port. The default service is `http://127.0.0.1:8765` and exposes
 its configuration through `/health`. Inspect an existing Profile's address and expected settings
 when locating that service. A custom `serviceCommand` supplies its own installation and start command.
-`hypit programs status` checks the Programs selected by the supplied Profile; `programs up` prepares
-and starts them. The managed installation does not require a global `whisperx` shell command.
+`hypit programs prepare --endpoint <instance>` prepares the configured ASR model, requested alignment
+models and sentence data without starting a process. It also works when the service is already online.
+`programs up` prepares and starts the selected Programs; `programs status` reports process readiness.
+Adding a language requires preparation, not a service restart, when its cache location is unchanged.
+`modelCacheDirectory` optionally selects a root with `huggingface/` and `torch/` subdirectories;
+relative paths resolve against the Runtime data root. Omission retains the upstream Hugging Face and
+torch caches and their environment settings. Changing a running service's cache selection requires
+an explicit restart when idle, just like changing its model or hardware. The managed installation
+does not require a global `whisperx` shell command.
 
 Preparation and service processes inherit the environment of the command starting them. Set
 network and cache variables there before `programs up` or `runtime up`. A service already running
 retains its earlier environment. Inspect its reported log before deciding whether a selected
 Program needs restarting, and account for active work using it.
 
+If NLTK refuses a proxied fetch during preparation, follow the service’s
+[explicit proxy preparation](../../services/whisperx/README.md#preparing-sentence-data-through-a-proxy).
+
 Preparation commands write `install.log`; the running service writes `program.log`, with stderr in
 `program.err.log` on Windows. Inspect the stderr file for Python model-loading and download messages.
 `programs status` reports these files as `installationLogPath`, `logPath` and `errorLogPath` when they
-exist, even before installation finishes. Preparation notices name the Python environment and NLTK
-commands separately. The service logs the start and completion of ASR loading, transcription,
-language-alignment model loading and alignment, with elapsed times. Loading may include a download;
-transfer details come from the underlying client, not an estimated percentage from the Provider.
+exist, even before installation finishes. Preparation notices name the Python environment and selected model/language resources separately. The service logs the start and completion of ASR loading, transcription,
+language-alignment model loading and alignment, with elapsed times. Downloads happen only in
+preparation; startup and inference only load local resources. A missing resource fails with a
+preparation instruction. Transfer details come from the underlying client during preparation.
 The service health endpoint becomes available after ASR loading. A startup readiness wait expiring
 can leave that process still loading. Its PID is recorded when spawned; repeated `up` observes it,
 and `programs down` can stop it during loading. PID liveness and service readiness are separate facts.