@hypit/hypit 0.1.13 → 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/package.json

@@ -27,6 +27,7 @@
     "typescript": "5.9.3"
   },
   "devDependencies": {
+    "@hypit/runtime-local": "workspace:*",
     "@hypit/markup": "workspace:*",
     "@hypit/run-markup": "workspace:*",
     "@hypit/workspace-fs-node": "workspace:*"

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"
@@ -364,13 +371,10 @@ export async function runEnvironmentCommand(input: {
     }
     const credentialsControl = await (await runtimeHost(runtimeProfile)).openCredentials(args.endpoint);
     try {
-      let credentials = await credentialsControl.credentials(args.endpoint);
-      if (args.slot !== undefined) credentials = credentials.filter((item) => item.slot === args.slot);
-      if (credentials.length === 0) throw new Error(`Endpoint ${args.endpoint} has no matching credential`);
-      if (args.slot === undefined && credentials.length > 1 && args.action !== "status") {
-        throw new Error(`Endpoint ${args.endpoint} has several credentials; select one with --slot`);
-      }
       if (args.action === "status") {
+        let credentials = await credentialsControl.credentials(args.endpoint);
+        if (args.slot !== undefined) credentials = credentials.filter((item) => item.slot === args.slot);
+        if (credentials.length === 0) throw new Error(`Endpoint ${args.endpoint} has no matching credential`);
         const view = credentials.slice(0, args.limit).map((item) => ({
           endpoint: item.endpoint,
           slot: item.slot,
@@ -397,7 +401,15 @@ export async function runEnvironmentCommand(input: {
             : `login opens OAuth: ${item.acquisition.authorizationEndpoint}`;
           return `${item.slot}: ${item.configured ? "configured" : "missing"} · ${item.writable ? "writable" : "read-only"} · ${entry}`;
         }));
-      } else if (args.action === "login") {
+        return;
+      }
+      let credentials = await credentialsControl.describeCredentials(args.endpoint);
+      if (args.slot !== undefined) credentials = credentials.filter((item) => item.slot === args.slot);
+      if (credentials.length === 0) throw new Error(`Endpoint ${args.endpoint} has no matching credential`);
+      if (args.slot === undefined && credentials.length > 1) {
+        throw new Error(`Endpoint ${args.endpoint} has several credentials; select one with --slot`);
+      }
+      if (args.action === "login") {
         const [item] = credentials;
         if (item === undefined) throw new Error(`Endpoint ${args.endpoint} has no matching credential`);
         if (!item.writable) {

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/main.ts

@@ -148,7 +148,8 @@ export async function runCli(
     }, "Runtime Profile created", "success", [
       ["Profile", selected.profile],
       ["Project", selected.projectRoot],
-    ], ["No package was installed, no service was contacted and no Worker was started."]);
+    ], ["Review the Profile’s credential stores and Endpoint settings before login or runtime up.",
+      "No package was installed, no service was contacted and no Worker was started."]);
     return;
   }
   if (args.command === "runtime" && args.action === "use") {

package/packages/cli/src/oauth.ts

@@ -28,6 +28,54 @@ function tokenExpiry(value: { readonly expires_at?: unknown; readonly expires_in
   return seconds === undefined ? undefined : Date.now() + seconds * 1_000;
 }
 
+export type AuthorizeBrowserLaunch = {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly windowsVerbatimArguments: boolean;
+  readonly env?: Readonly<Record<string, string>>;
+};
+
+/**
+ * Open the authorize URL in a browser. Windows `cmd /c start` treats `&` as a command
+ * separator unless the URL is a later quoted token after an explicit window title.
+ */
+export function authorizeBrowserLaunch(
+  url: string,
+  options: { readonly platform?: NodeJS.Platform; readonly comSpec?: string } = {},
+): AuthorizeBrowserLaunch {
+  const platform = options.platform ?? process.platform;
+  if (platform === "win32") {
+    // Expand one environment value after cmd parses the command. Interpolating the
+    // URL into command text would also expand percent sequences inside the URL.
+    const serialized = new URL(url).href;
+    return {
+      command: options.comSpec ?? process.env.ComSpec ?? "cmd.exe",
+      args: ["/d", "/s", "/v:off", "/c", 'start "" "%HYPIT_OAUTH_AUTHORIZE_URL%"'],
+      windowsVerbatimArguments: true,
+      env: { HYPIT_OAUTH_AUTHORIZE_URL: serialized },
+    };
+  }
+  return {
+    command: platform === "darwin" ? "open" : "xdg-open",
+    args: [url],
+    windowsVerbatimArguments: false,
+  };
+}
+
+function openAuthorizeUrl(url: string): void {
+  const launch = authorizeBrowserLaunch(url);
+  const child = spawn(launch.command, [...launch.args], {
+    stdio: "ignore",
+    detached: true,
+    windowsHide: true,
+    windowsVerbatimArguments: launch.windowsVerbatimArguments,
+    ...(launch.env === undefined ? {} : { env: { ...process.env, ...launch.env } }),
+  });
+  // A missing opener must not crash the CLI; the URL is already on the progress line.
+  child.once("error", () => undefined);
+  child.unref();
+}
+
 /** Acquire one OAuth credential from the exact data declared by its Endpoint package. */
 export async function acquireOAuthCredential(
   acquisition: CredentialAcquisition,
@@ -102,13 +150,8 @@ export async function acquireOAuthCredential(
   authorize.searchParams.set("code_challenge", challenge);
   authorize.searchParams.set("code_challenge_method", "S256");
   options.onProgress?.(`Opening sign-in: ${authorize}`);
-  if (options.open === undefined) {
-    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
-    const openerArgs = process.platform === "win32" ? ["/c", "start", "", authorize.toString()] : [authorize.toString()];
-    spawn(opener, openerArgs, { stdio: "ignore", detached: true, windowsHide: true }).unref();
-  } else {
-    options.open(authorize.toString());
-  }
+  if (options.open === undefined) openAuthorizeUrl(authorize.toString());
+  else options.open(authorize.toString());
   const code = await callback;
   options.onProgress?.("Authorization returned. Exchanging token…");
   const deadline = AbortSignal.timeout(acquisition.requestTimeoutMs);

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>]",