@hypit/hypit 0.1.2 → 0.1.4

package/packages/build-result/src/types.ts

@@ -1,3 +1,4 @@
+import { assertOrderedBuildId } from "@hypit/protocol";
 import type {
   BlobRef,
   BuildState,
@@ -9,12 +10,19 @@ import type {
 export type BuildResultOutcome = "complete" | "failed" | "cancelled";
 
 export type BuildResultFileRef = {
+  readonly size: number;
+  readonly mediaType: string;
+} & ({
   readonly kind: "build-file";
+  /** Absent for a file owned by the containing Result; explicit when reused elsewhere. */
+  readonly build?: string;
   /** Forward-only path relative to the owning Build's result directory. */
   readonly path: string;
-  readonly size: number;
-  readonly mediaType: string;
-};
+} | {
+  readonly kind: "external-file";
+  /** Explicit address supplied by the Workspace; remains a live external dependency. */
+  readonly uri: string;
+});
 
 /** A normalized half-open byte range within one Result file. */
 export type BuildResultFileRange = {
@@ -38,7 +46,7 @@ export type BuildResultResourceBinding = {
 
 /**
  * Durable encoding of one Composite value. Domain data stays ordinary canonical data while
- * Result-local Resource addresses live beside it, so reserved-looking domain objects cannot be
+ * Resource references live beside it, so reserved-looking domain objects cannot be
  * mistaken for persistence metadata.
  */
 export type BuildResultValueDocument = {
@@ -77,12 +85,18 @@ export function assertBuildResultFileRef(value: unknown, subject: string): asser
     throw new Error(`${subject} is not a Build file reference`);
   }
   const item = value as Readonly<Record<string, unknown>>;
-  if (item.kind !== "build-file"
+  if ((item.kind !== "build-file" && item.kind !== "external-file")
     || typeof item.size !== "number" || !Number.isSafeInteger(item.size) || item.size < 0
     || typeof item.mediaType !== "string" || item.mediaType.length === 0) {
     throw new Error(`${subject} is not a valid Build file reference`);
   }
-  assertBuildResultPath(item.path, `${subject}.path`);
+  if (item.kind === "external-file") {
+    if (typeof item.uri !== "string" || item.uri.length === 0) throw new Error(`${subject}.uri is missing`);
+    new URL(item.uri);
+  } else {
+    assertBuildResultPath(item.path, `${subject}.path`);
+    if (item.build !== undefined) assertOrderedBuildId(item.build as string);
+  }
 }
 
 function valueAtPath(value: CanonicalValue, path: BuildResultValuePath, subject: string): CanonicalValue {
@@ -150,6 +164,8 @@ export type BuildResultOutputValue =
   | { readonly kind: "value"; readonly path: string };
 
 export type BuildResultOutput = {
+  /** Author-provided display name; the Output identifier remains unchanged. */
+  readonly displayName?: string;
   readonly type: TypeRef;
   readonly value: BuildResultOutputValue;
 };
@@ -198,6 +214,8 @@ export type FinishedBuildResultManifest = BuildResultManifest & {
 };
 
 export type BuildResultPublishedOutput = {
+  /** Author-provided display name; the Output identifier remains unchanged. */
+  readonly displayName?: string;
   readonly name: string;
   readonly output: string;
 };
@@ -217,6 +235,8 @@ export type BuildResultSeed = {
   readonly targets: readonly string[];
   readonly publishedOutputs: readonly BuildResultPublishedOutput[];
   readonly forwards?: readonly BuildResultForward[];
+  /** Known file locations for admitted Resource identities, including nested uses. */
+  readonly resourceReferences?: Readonly<Record<string, BuildResultFileRef>>;
 };
 
 /** Validate the one-name-per-Output public Result surface before storage is touched. */
@@ -224,6 +244,11 @@ export function assertBuildResultSeed(seed: BuildResultSeed): void {
   if (seed.title !== undefined && seed.title.trim().length === 0) {
     throw new Error("Build Result title must not be empty");
   }
+  for (const [resource, file] of Object.entries(seed.resourceReferences ?? {})) {
+    if (resource.length === 0) throw new Error("Resource reference has no identity");
+    assertBuildResultFileRef(file, `Resource ${resource}`);
+    if (file.kind === "build-file" && file.build === undefined) throw new Error(`Resource ${resource} needs its owning Build`);
+  }
   const names = new Set<string>();
   const outputs = new Set<string>();
   for (const published of seed.publishedOutputs) {
@@ -275,6 +300,8 @@ export type BuildResultFinish = {
 };
 
 export type BuildResultPresentationUpdate = {
+  /** Exact public Output names; null removes an override. */
+  readonly outputDisplayNames?: Readonly<Record<string, string | null>>;
   /** `null` removes the current title; omission leaves it unchanged. */
   readonly title?: string | null;
   /** `null` removes the current note; omission leaves it unchanged. */
@@ -325,13 +352,14 @@ export type RepositoryBuildResultOutputDescription = {
 
 export type BuildResultWriter = {
   read(): Promise<BuildResultManifest>;
+  /** Publish newly accepted public Outputs; no storage writes when none are new. */
   sync(input: BuildResultSync): Promise<BuildResultManifest>;
   finish(input: BuildResultFinish): Promise<BuildResultManifest>;
 };
 
 /**
- * Project result history addressed only by Build id, Output name and Build-relative file path.
- * Filesystem paths, bucket keys and service URLs remain implementation details.
+ * Project result history addressed by Build id and Output name. File references carry their
+ * ownership or explicit external address; each repository supplies the corresponding byte access.
  */
 export type BuildResultRepository = {
   create(seed: BuildResultSeed): Promise<BuildResultWriter>;
@@ -346,6 +374,8 @@ export type BuildResultRepository = {
   /** Follow explicit Output forwarding and describe its terminal value without opening content. */
   describeOutput(build: string, output: string): Promise<RepositoryBuildResultOutputDescription | undefined>;
   resolve(build: string, output: string): Promise<RepositoryBuildResultOutput | undefined>;
+  /** Read current metadata for a file reference, including external dependencies. */
+  describeFile(build: string, file: BuildResultFileRef): Promise<BuildResultFileRef>;
   openFile(
     build: string,
     file: BuildResultFileRef,

package/packages/build-result/src/writer.ts

@@ -13,8 +13,9 @@ import type {
 
 export type BuildResultWriterState = {
   readonly resources: Readonly<Record<string, string>>;
+  readonly resourceReferences?: Readonly<Record<string, BuildResultFileRef>>;
   readonly values: Readonly<Record<string, string>>;
-  readonly publishedOutputs: readonly { readonly name: string; readonly output: string }[];
+  readonly publishedOutputs: readonly { readonly name: string; readonly output: string; readonly displayName?: string }[];
   readonly forwards: readonly { readonly output: string; readonly build: string; readonly sourceOutput: string }[];
 };
 
@@ -28,6 +29,8 @@ export type BuildResultWriteTarget = {
 };
 
 export type BuildResultSyncResult = {
+  /** Whether accepted public Outputs were added to the manifest. */
+  readonly changed: boolean;
   readonly manifest: BuildResultManifest;
   readonly writer: BuildResultWriterState;
 };
@@ -97,6 +100,8 @@ export async function syncBuildResultOutputs(input: {
   const outputs: Record<string, BuildResultOutput> = { ...input.manifest.outputs };
 
   const materialize = async (artifact: BlobRef): Promise<BuildResultFileRef> => {
+    const reference = input.writer.resourceReferences?.[artifact.resource];
+    if (reference !== undefined) return { ...reference, mediaType: artifact.mediaType };
     const identity = artifact.resource;
     assert(identity.length > 0, "Build resource has no instance identity");
     let path = resources.get(identity);
@@ -166,14 +171,20 @@ export async function syncBuildResultOutputs(input: {
   }).sort((left, right) => outputRank(left.record, left.forward) - outputRank(right.record, right.forward)
     || left.published.name.localeCompare(right.published.name));
 
+  if (ready.length === 0) {
+    return { changed: false, manifest: input.manifest, writer: input.writer };
+  }
+
   for (const { published, record, forward } of ready) {
     outputs[published.name] = {
+      ...(published.displayName === undefined ? {} : { displayName: published.displayName }),
       type: record.type,
       value: forward ?? await outputValue(record),
     };
   }
 
   return {
+    changed: true,
     manifest: { ...input.manifest, outputs },
     writer: {
       ...input.writer,

package/packages/build-result-fs/README.md

@@ -15,7 +15,7 @@ An explicit selection can move the same repository elsewhere:
 ```
 
 Relative paths are resolved from the project root. Results are grouped by the UTC date already encoded
-in their ordered Build ids, and each Build then owns one intact directory with its `result.json`, public
+in their ordered Build ids. Each Build has a directory containing its `result.json`, new public
 Resource files and Composite Value Documents:
 
 ```text
@@ -27,3 +27,25 @@ project-wide history database. Browsing sorts the shallow date buckets and enume
 only inside the dates reached while filling the requested cursor page; only those Result manifests are
 opened. File reads support byte ranges. Active diagnosis checks the selected directory (or its nearest
 existing parent) for read/write access without creating a probe file.
+
+Existing resources keep their addresses, including inside nested Composite values. External Workspace
+files remain live references; reused Result files retain their original owning Build. See the shared
+[Result value and reference model](../build-result/README.md) for ownership and export behavior.
+
+## Publication
+
+Runtime execution state stays in the Runtime's store. Result synchronization publishes newly accepted
+public Outputs: it saves new Resource files and Value Documents, then replaces `result.json`.
+Internal graph progress and already published Outputs cause no Result writes. A private `.writer.json`
+holds the file assignments needed while publishing and is removed at completion. The Runtime saves
+all accepted public Outputs and the final outcome before removing active execution state, including
+when the Build fails or is cancelled.
+
+Files are written completely beside their destination before publication. POSIX systems use `rename`;
+Windows uses `SetFileInformationByHandle(FileRenameInfoEx)` with replacement and POSIX semantics through
+Koffi. Existing readers keep their old file, while subsequent opens see the new one. This platform code
+belongs to the filesystem implementation; the Result model and other repository adapters do not
+depend on it. A filesystem that rejects this operation reports the Windows error without timed retries.
+
+The Windows behavior is defined by Microsoft's
+[FileRenameInformationEx documentation](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/4217551b-d2c0-42cb-9dc1-69a716cf6d0c).

package/packages/build-result-s3/README.md

@@ -33,6 +33,11 @@ The repository exposes the same logical shape as the filesystem adapter:
 Filesystem and S3 use the same Record-to-Result encoder. The adapter only writes the selected
 relative document or byte path; it does not interpret domain values. A Value Document keeps canonical
 domain data separate from the paths of nested Resources.
+Nested reuse retains each Resource's original Build and path. Workspace files remain explicit external
+references rather than being uploaded merely because this repository uses S3. The shared
+[Result value and reference model](../build-result/README.md) describes ownership and external access.
+Synchronization uploads new public Outputs and then their updated manifest. Internal graph progress
+and repeated synchronization of already published Outputs produce no object writes.
 
 Physical object prefixes use a reversible descending-time form derived from the ordered Build id, so
 S3 can return a newest-first delimiter page directly. This is only adapter key layout: callers still

package/packages/build-result-s3/src/repository.ts

@@ -1,5 +1,6 @@
 import type {
   BuildResultFileRef,
+  ExternalFileAccess,
   BuildResultFileRange,
   BuildResultFinish,
   BuildResultManifest,
@@ -22,6 +23,8 @@ import {
   encodeBuildResultManifest,
   normalizeBuildResultForwards,
   syncBuildResultOutputs,
+  currentFileReference,
+  localExternalFiles,
 } from "@hypit/build-result";
 import { assertOrderedBuildId, buildIdCreatedAt } from "@hypit/protocol";
 
@@ -31,6 +34,7 @@ import type { AwsBuildResultS3ClientOptions, BuildResultS3Client } from "./clien
 export type S3BuildResultRepositoryOptions = AwsBuildResultS3ClientOptions & {
   readonly prefix?: string;
   readonly client?: BuildResultS3Client;
+  readonly externalFiles?: ExternalFileAccess;
 };
 
 function assert(condition: unknown, message: string): asserts condition {
@@ -102,6 +106,7 @@ class S3BuildResultWriter implements BuildResultWriter {
         },
       },
     });
+    if (!updated.changed) return manifest;
     await this.#repository.writeWriter(this.#build, updated.writer);
     await this.#repository.writeManifest(this.#build, updated.manifest);
     return updated.manifest;
@@ -132,10 +137,12 @@ class S3BuildResultWriter implements BuildResultWriter {
 export class S3BuildResultRepository implements BuildResultRepository {
   readonly #client: BuildResultS3Client;
   readonly #prefix: string;
+  readonly #externalFiles: ExternalFileAccess;
 
   constructor(options: S3BuildResultRepositoryOptions) {
     assert(options.bucket.trim().length > 0, "S3 Build Result bucket must not be empty");
     this.#prefix = normalizePrefix(options.prefix);
+    this.#externalFiles = options.externalFiles ?? localExternalFiles;
     this.#client = options.client ?? new AwsBuildResultS3Client(options);
   }
 
@@ -194,6 +201,7 @@ export class S3BuildResultRepository implements BuildResultRepository {
         resources: {},
         values: {},
         publishedOutputs: seed.publishedOutputs,
+        ...(seed.resourceReferences === undefined ? {} : { resourceReferences: seed.resourceReferences }),
         forwards,
       });
       await this.writeManifest(seed.id, manifest);
@@ -285,8 +293,9 @@ export class S3BuildResultRepository implements BuildResultRepository {
         currentOutput = entry.value.output;
         continue;
       }
-      return entry.value.kind === "build-file"
-        ? { type: entry.type, kind: "resource", size: entry.value.size, mediaType: entry.value.mediaType }
+      const file = entry.value.kind === "external-file" ? await currentFileReference(entry.value, this.#externalFiles) : entry.value;
+      return file.kind === "build-file" || file.kind === "external-file"
+        ? { type: entry.type, kind: "resource", size: file.size, mediaType: file.mediaType }
         : entry.value.kind === "value"
           ? { type: entry.type, kind: "composite" }
           : { type: entry.type, kind: "scalar" };
@@ -324,29 +333,34 @@ export class S3BuildResultRepository implements BuildResultRepository {
         };
       }
       const terminalKind = (entry.value as { readonly kind?: unknown }).kind;
-      assert(terminalKind === "build-file" || terminalKind === "inline",
+      assert(terminalKind === "build-file" || terminalKind === "external-file" || terminalKind === "inline",
         `Build ${currentBuild} Output ${currentOutput} has unsupported Result value kind ${String(terminalKind)}`);
       return {
         build: currentBuild,
         output: currentOutput,
         type: entry.type,
-        value: entry.value,
+        value: entry.value.kind === "external-file" ? await currentFileReference(entry.value, this.#externalFiles) : entry.value,
       };
     }
   }
 
+  async describeFile(_build: string, file: BuildResultFileRef): Promise<BuildResultFileRef> {
+    return await currentFileReference(file, this.#externalFiles);
+  }
+
   async openFile(
     build: string,
     file: BuildResultFileRef,
     range?: BuildResultFileRange,
   ): Promise<AsyncIterable<Uint8Array> | undefined> {
+    if (file.kind === "external-file") return await this.#externalFiles.open(file.uri, range);
     if (range !== undefined) {
       assert(Number.isSafeInteger(range.start) && range.start >= 0, "Build Result file range start is invalid");
       assert(Number.isSafeInteger(range.endExclusive) && range.endExclusive > range.start,
         "Build Result file range end is invalid");
       assert(range.endExclusive <= file.size, "Build Result file range exceeds the declared file size");
     }
-    return await this.#client.open(this.#key(build, file.path), range);
+    return await this.#client.open(this.#key(file.build ?? build, file.path), range);
   }
 
   /** Verify that the configured bucket/prefix can be listed without loading Result history. */

package/packages/caption-fine/README.md

@@ -97,8 +97,23 @@ font fallbacks supply the required glyphs; the layout does not select a font by
 Both count limits are omitted above so the example flows by available width. For a compact
 single-line treatment, author coherent Cues and choose a font, size and width that fit those Cues.
 `karaoke: off` keeps a complete Cue steady; `current` and `trail` follow its timed units, which are
-normally individual characters in Chinese. The Hypit Skill's Caption craft page owns grouping and
-visual direction.
+normally individual characters in Chinese.
+
+| Effect | Recipe | Visible behavior |
+| --- | --- | --- |
+| Whole-character emphasis | `karaoke: current; karaoke-transition: step` | The complete current unit takes the active Paint at its start, returning to base Paint at its end. |
+| Accumulating emphasis | `karaoke: trail; karaoke-transition: step` | Each complete unit takes the active Paint at its start and keeps it for the rest of the Cue. |
+| Sweeping fill | `karaoke: trail; karaoke-transition: wipe` | Paint sweeps inside each unit's glyphs during that unit's own time window. |
+| Spoken-unit appearance | `atom-reveal: on-start` | Each complete unit appears at its start. |
+| Typing appearance | `atom-reveal: typewriter` | Whole graphemes appear in sequence within each unit, starting with its first grapheme at the unit's start. A normal Han unit appears as a complete character. |
+
+`step` is the default Karaoke transition. Choose it for ordinary Chinese character highlighting;
+`wipe` deliberately produces partial glyph fills. Cue width and duration do not supply a substitute
+clock for either mode. `atom-reveal` controls text appearing, independently of Karaoke recoloring
+already visible text. A Dual Text span shares one timing unit, so its display words activate together
+under `step`; keep pronunciation markup scoped to the name or expression that needs it.
+
+The Hypit Skill's Caption craft page owns grouping and visual direction.
 
 `font` accepts an exact face or ordered stack. A local file declared through `media:Font` can be the
 primary face or a `<caption-fine:Fallback font={...}/>` child, just like a bundled face. See

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

@@ -206,7 +206,7 @@ export const captionFineMarkupSurfaces = [
               { name: "karaoke", required: false, values: ["off", "current", "trail"], fallback: "off",
                 summary: "Decides whether the active Paint marks only the Word being spoken or every Word up to it." },
               { name: "karaoke-transition", required: false, values: ["step", "wipe"], fallback: "step",
-                summary: "Decides whether the karaoke Paint snaps at the Word boundary or sweeps across the glyphs." },
+                summary: "step activates each whole timed unit at its start (normally one Han character in Chinese); wipe sweeps inside that unit's glyphs during its own interval." },
               { name: "active-box", required: false, values: ["off", "current", "trail"], fallback: "off",
                 summary: "Decides whether a highlight box sits behind the Word being spoken or behind every Word up to it." },
               { name: "active-box-continuity", required: false, values: ["isolated", "joined"], fallback: "isolated",

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

@@ -480,23 +480,6 @@ function karaokeWipeAnimation(
   ] };
 }
 
-function typewriterAnimation(
-  text: string,
-  parameters: FineCaptionParameters,
-  startFrame: number,
-  endFrame: number,
-  durationFrames: number,
-): VisualAnimation | undefined {
-  if (parameters.motion.atomReveal !== "typewriter") return undefined;
-  const graphemes = Math.max(1, [...new Intl.Segmenter("und", { granularity: "grapheme" }).segment(text)].length);
-  const span = Math.max(1, endFrame - startFrame);
-  const offsets = Array.from({ length: graphemes + 1 }, (_, index) => startFrame + Math.round(span * index / graphemes));
-  return animationFrom(durationFrames, [...stepOffsets(startFrame), ...offsets], (frame) => {
-    const progress = frame < startFrame ? 0 : Math.floor(clamp((frame - startFrame) / span, 0, 1) * graphemes) / graphemes;
-    return [{ name: "clip-path", value: wipeClip(progress, parameters.layout.direction) }];
-  });
-}
-
 function activeResponseAnimation(
   parameters: FineCaptionParameters,
   startFrame: number,
@@ -867,9 +850,7 @@ function cueElements(
     // the karaoke wipe keeps sitting on the letterforms it reveals.
     const gaps = wordGaps(surfaces);
     const wordGap = uniformGap(gaps);
-    const atomText = joinSurfaces(surfaces, " ");
     const entryId = `${atomId}-entry`;
-    const typewriterId = `${atomId}-typewriter`;
     const loopId = `${atomId}-loop`;
     const responseId = `${atomId}-response`;
     if (parameters.layout.maxWordsPerLine !== undefined
@@ -884,7 +865,6 @@ function cueElements(
       wordsOnLine = 0;
     }
     const entryAnimation = atomLifecycleAnimation(parameters, timing.start, timing.end, durationFrames);
-    const writerAnimation = typewriterAnimation(atomText, parameters, timing.start, timing.end, durationFrames);
     const atomLoop = parameters.motion.loopTarget === "active-atom"
       ? loopAnimation(parameters, durationFrames, activationTiming) : undefined;
     const responseAnimation = activeResponseAnimation(
@@ -906,20 +886,9 @@ function cueElements(
       ],
       ...(entryAnimation === undefined ? {} : { animation: entryAnimation }),
     });
-    push({
-      id: typewriterId,
-      parent: entryId,
-      kind: "box",
-      style: [
-        { name: "display", value: "inline-flex" },
-        { name: "min-width", value: "0" },
-        { name: "transform-origin", value: parameters.layout.direction === "rtl" ? "right center" : "left center" },
-      ],
-      ...(writerAnimation === undefined ? {} : { animation: writerAnimation }),
-    });
     push({
       id: loopId,
-      parent: typewriterId,
+      parent: entryId,
       kind: "box",
       style: [
         { name: "display", value: "inline-flex" },
@@ -983,10 +952,53 @@ function cueElements(
         attributes: [{ name: "data-caption-active-box", value: "isolated" }],
       });
     }
+    const graphemes = parameters.motion.atomReveal === "typewriter"
+      ? surfaces.map((text) =>
+        [...new Intl.Segmenter("und", { granularity: "grapheme" }).segment(text)].map((part) => part.segment))
+      : [];
+    const graphemeCount = graphemes.reduce((sum, word) => sum + word.length, 0);
+    const pushText = (element: Omit<VisualTextElement, "order">, wordIndex: number): void => {
+      if (parameters.motion.atomReveal !== "typewriter") {
+        push(element);
+        return;
+      }
+      // Reveal complete glyphs, not fractions of a Word's width. Variable-width Latin letters,
+      // Han characters and combining sequences all retain their actual layout widths.
+      const isMargin = (name: string): boolean => name.startsWith("margin-");
+      push({
+        id: element.id,
+        ...(element.parent === undefined ? {} : { parent: element.parent }),
+        kind: "box",
+        style: [
+          { name: "display", value: "inline" },
+          { name: "min-width", value: "0" },
+          ...element.style.filter(({ name }) => isMargin(name) || name === "opacity"),
+        ],
+        ...(element.attributes === undefined ? {} : { attributes: element.attributes }),
+      });
+      const preceding = graphemes.slice(0, wordIndex).reduce((sum, word) => sum + word.length, 0);
+      const { attributes: _attributes, ...glyph } = element;
+      for (const [index, text] of (graphemes[wordIndex] ?? []).entries()) {
+        const revealFrame = timing.start + Math.floor(
+          (timing.end - timing.start) * (preceding + index) / Math.max(1, graphemeCount),
+        );
+        push({
+          ...glyph,
+          id: `${element.id}-grapheme-${index + 1}`,
+          parent: element.id,
+          text,
+          style: [
+            ...element.style.filter(({ name }) => !isMargin(name) && name !== "opacity"),
+            { name: "display", value: "inline" },
+          ],
+          animation: activationStepAnimation("trail", revealFrame, durationFrames, durationFrames),
+        });
+      }
+    };
     for (const [wordIndex, wordId] of atom.wordIds.entries()) {
       const text = wordText.get(wordId);
       if (text === undefined) throw new Error(`Fine Caption Atom references unknown word ${wordId}`);
-      push({
+      pushText({
         id: `${atomId}-base-${wordIndex + 1}`,
         parent: atomId,
         kind: "text",
@@ -997,7 +1009,7 @@ function cueElements(
         ],
         ...glyphPaintFields(parameters.basePaint),
         fonts,
-      });
+      }, wordIndex);
     }
     const addActivatedTextLayer = (
       suffix: string,
@@ -1026,7 +1038,7 @@ function cueElements(
       });
       for (const [wordIndex, wordId] of atom.wordIds.entries()) {
         const text = wordText.get(wordId)!;
-        push({
+        pushText({
           id: `${activeId}-${wordIndex + 1}`,
           parent: activeId,
           kind: "text",
@@ -1041,7 +1053,7 @@ function cueElements(
           ...(kind === "glyph" ? glyphPaintFields(parameters.activePaint) : {}),
           fonts,
           attributes: [{ name: kind === "glyph" ? "data-caption-active-word" : "data-caption-underlined-word", value: wordId }],
-        });
+        }, wordIndex);
       }
     };
     if (parameters.karaoke.mode !== "off") addActivatedTextLayer("active", parameters.karaoke.mode, "glyph");

package/packages/caption-fine-studio/package.json

@@ -4,12 +4,17 @@
   "license": "SEE LICENSE IN LICENSE",
   "private": true,
   "type": "module",
-  "exports": { ".": "./src/index.ts" },
-  "hypit": { "activation": "./src/activation.ts" },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
   "dependencies": {
     "@hypit/caption-fine": "workspace:*",
     "@hypit/composition": "workspace:*",
     "@hypit/narrative": "workspace:*",
-    "@hypit/studio-adapter": "workspace:*"
+    "@hypit/studio-adapter": "workspace:*",
+    "@hypit/fonts-open": "workspace:*"
   }
 }

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

@@ -1,3 +1,4 @@
+import { openFontStudioFields } from "@hypit/fonts-open/studio";
 import { captionFineMarkupSurfaces, captionFineModuleRef } from "@hypit/caption-fine";
 import type { FineCaptionSchedule } from "@hypit/caption-fine";
 import { compositionTypes } from "@hypit/composition";
@@ -12,6 +13,9 @@ import type {
 import { requiredReferencedValue, requiredSurfaceValue, textLayer } from "@hypit/studio-adapter";
 
 const styleSurface = captionFineMarkupSurfaces.find((surface) => surface.name === "style");
+
+const fontInspector = openFontStudioFields("program");
+
 const recipeVocabulary = styleSurface?.vocabulary.attributes
   .find((attribute) => attribute.name === "recipe")?.recipe ?? [];
 
@@ -83,6 +87,8 @@ const captionColorProperties = new Set([
   "active-underline-color", "active-box-background", "active-box-border-color",
 ]);
 const captionTextProperties = new Set(["loop"]);
+const captionPercentProperties = new Set(["x", "y", "width", "height", "opacity", "active-opacity", "active-scale"]);
+const captionPixelProperties = new Set(["size", "letter-spacing", "word-gap", "radius", "stroke-width", "border-width", "shadow-blur", "glow-blur"]);
 
 export const captionFineInspectorFields: readonly StudioInspectorFieldDeclaration[] = recipeVocabulary.map((property) => {
   const placement = captionPlacement.get(property.name);
@@ -96,6 +102,8 @@ export const captionFineInspectorFields: readonly StudioInspectorFieldDeclaratio
     control: options !== undefined ? "select" : captionColorProperties.has(property.name) ? "color"
       : captionTextProperties.has(property.name) ? "text" : "number",
     ...(options === undefined ? {} : { options }),
+    ...(captionPercentProperties.has(property.name) ? { unit: "%", number: { scale: 100, step: 1 } } : {}),
+    ...(captionPixelProperties.has(property.name) ? { unit: "px", number: { step: 1 } } : {}),
   };
 });
 
@@ -153,10 +161,11 @@ export const captionFineStudioTrackCompanions: readonly StudioTrackCompanion[] =
     bindings: [
       {
         name: "program",
+        referenced: [fontInspector.binding],
         recipe: { through: ["recipe"], bindings: recipeVocabulary.map(({ name }) => ({ name })) },
       },
     ],
-    inspector: captionFineInspectorFields,
+    inspector: [...fontInspector.fields, ...captionFineInspectorFields],
     requiredValues: ["schedule"], project: projectCaption,
     lane: { heightPx: 48 },
   },

package/packages/cli/README.md

@@ -15,6 +15,31 @@ Human output is compact by default. `--json` emits a command-specific view rathe
 Runtime or Repository objects. `--verbose` adds operational detail; it never turns the command into
 an internal state dump.
 
+## Project and Runtime context
+
+`--workspace` explicitly selects the project. Otherwise the nearest `package.json` above the command's
+current directory establishes its root; with none, the current directory is the root. Source and Run
+arguments locate files within that context. Relative command-line paths are resolved from the current
+directory, including when `--workspace` is supplied.
+
+Runtime-aware commands use an explicit `--runtime` for that invocation, or read exactly the resolved
+project's `.hypit/runtime` pointer. `runtime use` writes the pointer; a Profile filename by itself does
+not select it. Project selection is also available on `paths`, `doctor`, execution status/control,
+Runtime operations, `programs` and `auth`. Machine-wide `packages` operations have no project selector.
+
+`paths` shows the effective locations and whether the Profile came from a command argument, a project
+selection or neither. Its JSON fields `profileSource` and `selectionFile` expose that distinction; the
+selection-file location is shown even when no selection exists. `doctor` states whether it checked
+only project Results or also a selected Runtime. An unselected Runtime is not a completed environment
+diagnosis. Result repository selection and project-package resolution remain independent of Runtime.
+
+For a command invoked outside the project, name both the project and its input explicitly:
+
+```bash
+hypit paths --workspace /path/to/video-project
+hypit plan /path/to/video-project/build.svrun --workspace /path/to/video-project
+```
+
 `plan` lists every Endpoint request in the frozen Build graph. Exact-model packages expose their own
 port tables and request-assembly edges, so the CLI can show authored prompt, duration and generation
 settings without searching arbitrary records for a request-shaped object. When an input file will be