@hypit/hypit 0.1.14 → 0.2.1

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-file/README.md

@@ -4,7 +4,9 @@ A writable CredentialStore for a deployment that explicitly chooses local file s
 Linux without an OS credential locker. It stores unencrypted credential values in an owner-private
 directory outside the video project. On Windows the selected directory must have a private user ACL;
 POSIX file modes do not set Windows ACLs. Choose `@hypit/credential-store-os` when using macOS Keychain
-or Windows Credential Locker, or `@hypit/credential-store-env` for externally supplied, read-only values.
+or Windows Credential Locker, `@hypit/credential-store-platform` for OS storage on macOS/Windows
+and this file Store on Linux or `@hypit/credential-store-env` for externally
+supplied, read-only values.
 
 ## Select it before login
 

package/packages/credential-store-os/README.md

@@ -11,3 +11,7 @@ bytes do not appear in command arguments or temporary files.
 
 Use `hypit auth login <endpoint> --runtime <profile>` to write the selected credential and
 `hypit auth logout` to remove it.
+
+A Profile that must also run on Linux can select `@hypit/credential-store-platform`:
+that package uses this Store on macOS and Windows, and an unencrypted, owner-private file on Linux.
+Selecting `@hypit/credential-store-os` directly continues to require macOS or Windows.

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/credential-store-platform/README.md

@@ -0,0 +1,62 @@
+# `@hypit/credential-store-platform`
+
+An explicitly selected CredentialStore policy: macOS Keychain on macOS, Windows Credential Locker
+on Windows, and an unencrypted, owner-private file on Linux. Other platforms are unsupported by this
+package and report an error. Linux may offer other credential services; this package chooses file
+storage there and does not detect or integrate those services.
+
+A Profile can select this package to use that policy on Linux, macOS and Windows.
+`@hypit/credential-store-os`, `@hypit/credential-store-file` and `@hypit/credential-store-env`
+remain selectable directly for a deployment with a different storage choice.
+
+## Select it
+
+```json
+{
+  "credentials": {
+    "platform": { "use": "@hypit/credential-store-platform" }
+  },
+  "endpoints": {
+    "hypihub.default": {
+      "use": "@hypit/provider-hypihub",
+      "config": {
+        "baseUrl": "https://hypit.ai",
+        "apiKey": { "store": "platform", "key": "hypihub.oauth" }
+      }
+    }
+  }
+}
+```
+
+The Endpoint still owns its acquisition flow and the Store only persists the result:
+
+```bash
+hypit auth login hypihub.default --runtime <profile>
+hypit auth status hypihub.default --runtime <profile>
+hypit auth logout hypihub.default --runtime <profile>
+```
+
+## What it does not do
+
+The choice is made once per host, from the platform the Runtime is running on. This is not a lookup
+chain: a miss or failure in one store never tries another, and no credential is migrated between them. A
+credential stored in a locker stays in that locker; a credential stored in a file stays in that file.
+
+## Configuration
+
+- `path` selects the directory for Linux file storage, resolved against the Host state root printed by
+  `hypit paths`. The default is the same `credentials` directory `@hypit/credential-store-file` uses,
+  so on Linux, switching between the two Stores finds the credential already stored.
+- `service` selects the locker service name. The OS Store's own default applies when it is absent.
+
+## Storage on each platform
+
+On macOS and Windows the credential is held by the platform locker, with exactly the rules of
+`@hypit/credential-store-os`: it is encrypted and access-controlled by the operating system, and it
+is not readable from another machine.
+
+On Linux the credential is held by an owner-private document with exactly the rules of
+`@hypit/credential-store-file`: unencrypted JSON, one document per key, directory mode `0700`, file
+mode `0600`, outside the video project, and never enumerated or indexed. Filesystem path-length
+limits apply to an overlong key, which fails rather than selecting another name. A damaged document
+can be replaced by `auth login` or deleted by `auth logout` without decoding the old value.

package/packages/credential-store-platform/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@hypit/credential-store-platform",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/credential-store-file": "workspace:*",
+    "@hypit/credential-store-os": "workspace:*",
+    "@hypit/runtime": "workspace:*",
+    "@hypit/runtime-kit": "workspace:*"
+  }
+}