@hypit/hypit 0.0.1 → 0.1.0

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

@@ -0,0 +1,152 @@
+import { captionTypes } from "@hypit/caption";
+import { assertFontArtifactRef, assertFontStackRef, mediaTypes } from "@hypit/media";
+import type { FontArtifactRef, FontStackRef } from "@hypit/media";
+import { narrativeTypes } from "@hypit/narrative";
+import { semanticTrackTypes } from "@hypit/semantic-track";
+import { spatialTypes } from "@hypit/spatial";
+import { svsRecipeType } from "@hypit/svs";
+import type { SvsRecipe } from "@hypit/svs";
+import type {
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceResolvedReference,
+  MarkupAttributeValue,
+} from "@hypit/markup";
+
+import { fineCaptionRegionTrackFragment, fineCaptionTrackFragment } from "./fragment.js";
+import { fineCaptionStyle } from "./style.js";
+
+function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
+  return left.module.name === right.module.name && left.module.version === right.module.version && left.name === right.name;
+}
+
+function attributes(element: StructuredElement, required: readonly string[], optional: readonly string[] = []): void {
+  const actual = Object.keys(element.attributes);
+  const allowed = new Set([...required, ...optional]);
+  if (required.some((name) => element.attributes[name] === undefined) || actual.some((name) => !allowed.has(name))) {
+    const suffix = optional.length === 0 ? "" : `, with optional ${optional.join(", ")}`;
+    throw new Error(`${element.name} requires ${required.join(", ")}${suffix}`);
+  }
+}
+
+function stringAttribute(element: StructuredElement, name: string): string {
+  const value = element.attributes[name];
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${element.name}.${name} must be a non-empty string`);
+  return value.trim();
+}
+
+function reference(
+  element: StructuredElement,
+  name: string,
+  expected: SurfaceResolvedReference["type"],
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  const raw: MarkupAttributeValue | undefined = element.attributes[name];
+  if (typeof raw !== "object" || raw.kind !== "reference") {
+    throw new Error(`${element.name}.${name} must be a whole-value reference`);
+  }
+  const value = resolveReference(raw.path);
+  if (value === undefined) throw new Error(`${element.name}.${name} cannot resolve ${raw.path}`);
+  if (!sameType(value.type, expected)) throw new Error(`${element.name}.${name} has the wrong type`);
+  return value;
+}
+
+function inline<T>(referenceValue: SurfaceResolvedReference, subject: string): T {
+  if (referenceValue.record?.value.kind !== "inline") throw new Error(`${subject} must reference an authored inline Record`);
+  return referenceValue.record.value.value as unknown as T;
+}
+
+function localName(name: string): string {
+  const colon = name.lastIndexOf(":");
+  return colon < 0 ? name : name.slice(colon + 1);
+}
+
+function exactFonts(
+  element: StructuredElement,
+  resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): FontArtifactRef[] {
+  const result: FontArtifactRef[] = [];
+  const primary = element.attributes.font;
+  if (primary === undefined) throw new Error(`${element.name} requires font`);
+  if (typeof primary !== "object" || primary.kind !== "reference") {
+    throw new Error(`${element.name}.font must be a whole-value reference`);
+  }
+  const resolved = resolveReference(primary.path);
+  if (resolved === undefined) throw new Error(`${element.name}.font cannot resolve ${primary.path}`);
+  if (sameType(resolved.type, mediaTypes.fontArtifact)) {
+    result.push(inline<FontArtifactRef>(resolved, `${element.name}.font`));
+  } else if (sameType(resolved.type, mediaTypes.fontStack)) {
+    const stack = inline<FontStackRef>(resolved, `${element.name}.font`);
+    assertFontStackRef(stack, `${element.name}.font`);
+    result.push(...stack.faces);
+  } else {
+    throw new Error(`${element.name}.font has the wrong type`);
+  }
+  for (const child of element.children) {
+    if (child.kind === "text") {
+      if (child.value.trim()) throw new Error(`${element.name} accepts only Fallback children`);
+      continue;
+    }
+    if (localName(child.name) !== "Fallback") throw new Error(`${element.name} accepts only Fallback children`);
+    attributes(child, ["font"]);
+    if (child.children.some((nested) => nested.kind === "element" || nested.value.trim())) {
+      throw new Error(`${child.name} does not accept children`);
+    }
+    result.push(inline<FontArtifactRef>(
+      reference(child, "font", mediaTypes.fontArtifact, resolveReference),
+      `${child.name}.font`,
+    ));
+  }
+  for (const [index, font] of result.entries()) assertFontArtifactRef(font, `${element.name}.font.${index + 1}`);
+  return result;
+}
+
+export const decodeFineCaptionStyleSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  attributes(element, ["id", "recipe", "font"]);
+  const id = stringAttribute(element, "id");
+  const recipe = inline<SvsRecipe>(reference(element, "recipe", svsRecipeType, resolveReference), `${element.name}.recipe`);
+  const style = fineCaptionStyle(id, recipe, exactFonts(element, resolveReference));
+  return {
+    records: [{ id, type: captionTypes.style, value: { kind: "inline", value: style }, range: element.range }],
+    components: [],
+    fragments: [],
+  };
+};
+
+export const decodeFineCaptionTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  attributes(element, ["id", "document", "semantic", "program"], ["regions"]);
+  if (element.children.some((child) => child.kind === "element" || child.value.trim())) {
+    throw new Error(`${element.name} does not accept children`);
+  }
+  const id = stringAttribute(element, "id");
+  const document = reference(element, "document", narrativeTypes.captionDocument, resolveReference);
+  const semantic = reference(element, "semantic", semanticTrackTypes.track, resolveReference);
+  const program = reference(element, "program", captionTypes.program, resolveReference);
+  if (element.attributes.regions !== undefined) {
+    const regions = reference(element, "regions", spatialTypes.regionTimeline, resolveReference);
+    return {
+      records: [],
+      components: [{
+        id,
+        fragment: fineCaptionRegionTrackFragment.id,
+        inputs: { document: document.ref, semantic: semantic.ref, program: program.ref, regions: regions.ref },
+        outputs: { schedule: `${id}.schedule`, track: `${id}.track` },
+        range: element.range,
+      }],
+      fragments: [fineCaptionRegionTrackFragment],
+    };
+  }
+  return {
+    records: [],
+    components: [{
+      id,
+      fragment: fineCaptionTrackFragment.id,
+      inputs: {
+        document: document.ref, semantic: semantic.ref, program: program.ref,
+      },
+      outputs: { schedule: `${id}.schedule`, track: `${id}.track` },
+      range: element.range,
+    }],
+    fragments: [fineCaptionTrackFragment],
+  };
+};

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

@@ -0,0 +1,191 @@
+import type { TimedCaptionUnit } from "@hypit/caption";
+import type { FontArtifactRef } from "@hypit/media";
+
+export type FineCaptionGlyphPaint = {
+  readonly fill: string;
+  readonly gradient?: {
+    readonly from: string;
+    readonly to: string;
+    readonly angleDeg: number;
+  };
+  readonly opacity: number;
+  readonly stroke: {
+    readonly color: string;
+    readonly widthPx: number;
+  };
+  readonly shadow: {
+    readonly color: string;
+    readonly opacity: number;
+    readonly offsetXPx: number;
+    readonly offsetYPx: number;
+    readonly blurPx: number;
+    readonly spreadPx: number;
+  };
+  readonly longShadow: {
+    readonly color: string;
+    readonly opacity: number;
+    readonly distancePx: number;
+    readonly angleDeg: number;
+  };
+  readonly glow: {
+    readonly color: string;
+    readonly opacity: number;
+    readonly blurPx: number;
+    readonly spreadPx: number;
+  };
+};
+
+export type FineCaptionUnderline = {
+  readonly mode: "off" | "always";
+  readonly color: string;
+  readonly thicknessPx: number;
+  readonly offsetPx: number;
+};
+
+export type FineCaptionActiveUnderline = Omit<FineCaptionUnderline, "mode"> & {
+  readonly mode: "off" | "current" | "trail";
+};
+
+export type FineCaptionBoxPaint = {
+  readonly mode: "off" | "current" | "trail";
+  readonly continuity: "isolated" | "joined";
+  readonly background: string;
+  readonly borderColor: string;
+  readonly borderWidthPx: number;
+  readonly paddingXPx: number;
+  readonly paddingYPx: number;
+  readonly radiusPx: number;
+  readonly enter: FineCaptionOneShotMotion;
+  readonly exit: FineCaptionOneShotMotion;
+  readonly transitionFrames: number;
+};
+
+export type FineCaptionOneShotMotion =
+  | "none"
+  | "fade"
+  | "pop"
+  | "scale"
+  | "spring"
+  | "bounce"
+  | "elastic"
+  | "stamp"
+  | "tilt"
+  | "zoom-blur"
+  | "flip-x"
+  | "flip-y"
+  | "spin"
+  | "squash"
+  | "stretch"
+  | "slide-left"
+  | "slide-right"
+  | "slide-up"
+  | "slide-down"
+  | "blur-in"
+  | "wipe-left"
+  | "wipe-right"
+  | "wipe-up"
+  | "wipe-down";
+
+export type FineCaptionParameters = {
+  readonly stackingOrder: number;
+  readonly placement: {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height?: number;
+    readonly anchorX: "left" | "center" | "right";
+    readonly anchorY: "top" | "center" | "bottom";
+  };
+  readonly layout: {
+    readonly textAlign: "left" | "center" | "right";
+    readonly blockAlign: "start" | "center" | "end";
+    readonly direction: "ltr" | "rtl";
+    readonly inlineSize: "hug" | "fixed";
+    readonly wrap: "word" | "grapheme";
+    readonly maxLines?: number;
+    readonly maxWordsPerLine?: number;
+    readonly lineHeight: number;
+    readonly letterSpacingPx: number;
+    readonly wordGapPx: number;
+  };
+  readonly typography: {
+    readonly fontSizePx: number;
+    readonly kerning: "auto" | "normal" | "none";
+    readonly variantCaps: "normal" | "small-caps" | "all-small-caps";
+    readonly textTransform: "none" | "uppercase" | "lowercase" | "capitalize";
+    readonly exactFonts: readonly FontArtifactRef[];
+  };
+  readonly basePaint: FineCaptionGlyphPaint;
+  readonly activePaint: FineCaptionGlyphPaint;
+  readonly underline: FineCaptionUnderline;
+  readonly activeUnderline: FineCaptionActiveUnderline;
+  readonly cueBox: {
+    readonly background: string;
+    readonly borderColor: string;
+    readonly borderWidthPx: number;
+    readonly paddingXPx: number;
+    readonly paddingYPx: number;
+    readonly radiusPx: number;
+    readonly shadow: {
+      readonly color: string;
+      readonly opacity: number;
+      readonly offsetXPx: number;
+      readonly offsetYPx: number;
+      readonly blurPx: number;
+      readonly spreadPx: number;
+    };
+  };
+  readonly karaoke: {
+    readonly mode: "off" | "current" | "trail";
+    readonly transition: "step" | "wipe";
+  };
+  readonly activeBox: FineCaptionBoxPaint;
+  readonly motion: {
+    readonly cueEnter: FineCaptionOneShotMotion;
+    readonly cueExit: FineCaptionOneShotMotion;
+    readonly cueEnterFrames: number;
+    readonly cueExitFrames: number;
+    readonly cueEnterStartScale?: number;
+    readonly atomEnter: FineCaptionOneShotMotion;
+    readonly atomEnterFrames: number;
+    readonly atomExit: FineCaptionOneShotMotion;
+    readonly atomExitFrames: number;
+    readonly atomReveal: "all" | "on-start" | "typewriter";
+    readonly activeResponse: FineCaptionOneShotMotion;
+    readonly activeResponseFrames: number;
+    readonly activeScale: number;
+    readonly slideDistancePx: number;
+    readonly loop: "none" | "shake" | "wobble" | "glow-pulse" | "breathe" | "float" | "pulse" | "flicker";
+    readonly loopTarget: "cue" | "active-atom";
+    readonly loopPeriodFrames: number;
+    readonly loopIntensity: number;
+  };
+  /**
+   * Public rules for projecting semantic Cue time into its visible envelope.
+   * The renderer never expands a Cue on its own; the package's schedule
+   * Producer resolves these rules before rendering.
+   */
+  readonly timing: {
+    readonly leadFrames: number;
+    readonly tailFrames: number;
+    readonly handoff: "cut" | "overlap";
+  };
+};
+
+export type FineCaptionScheduledCue = {
+  readonly id: string;
+  readonly styleId: string;
+  readonly semanticStartFrame: number;
+  readonly semanticEndFrameExclusive: number;
+  readonly visibleStartFrame: number;
+  readonly visibleEndFrameExclusive: number;
+  readonly units: readonly TimedCaptionUnit[];
+};
+
+/** Explicit projection consumed by the Fine renderer. */
+export type FineCaptionSchedule = {
+  readonly spaceId: string;
+  readonly narrativeId: string;
+  readonly documentId: string;
+  readonly cues: readonly FineCaptionScheduledCue[];
+};

package/packages/caption-fine-studio/README.md

@@ -0,0 +1,3 @@
+# `@hypit/caption-fine-studio`
+
+Hypit Studio Companion for `@hypit/caption-fine`. It projects the public Caption Schedule and owns the Inspector layout.

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

@@ -0,0 +1,15 @@
+{
+  "name": "@hypit/caption-fine-studio",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": { ".": "./src/index.ts" },
+  "hypit": { "activation": "./src/activation.ts" },
+  "dependencies": {
+    "@hypit/caption-fine": "workspace:*",
+    "@hypit/composition": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/studio-adapter": "workspace:*"
+  }
+}

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

@@ -0,0 +1,7 @@
+import { createStudioTrackCompanionHostFacet } from "@hypit/studio-adapter";
+import { captionFineStudioTrackCompanions } from "./index.js";
+
+export default {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [createStudioTrackCompanionHostFacet(captionFineStudioTrackCompanions)],
+};

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

@@ -0,0 +1,163 @@
+import { captionFineMarkupSurfaces, captionFineModuleRef } from "@hypit/caption-fine";
+import type { FineCaptionSchedule } from "@hypit/caption-fine";
+import { compositionTypes } from "@hypit/composition";
+import { narrativeTypes } from "@hypit/narrative";
+import type { CaptionDocument } from "@hypit/narrative";
+import type {
+  StudioTrackCompanion,
+  StudioTrackCompanionContext,
+  StudioEntityDraft,
+  StudioInspectorFieldDeclaration,
+} from "@hypit/studio-adapter";
+import { requiredReferencedValue, requiredSurfaceValue, textLayer } from "@hypit/studio-adapter";
+
+const styleSurface = captionFineMarkupSurfaces.find((surface) => surface.name === "style");
+const recipeVocabulary = styleSurface?.vocabulary.attributes
+  .find((attribute) => attribute.name === "recipe")?.recipe ?? [];
+
+function title(name: string): string {
+  return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+
+function valuesFor(property: typeof recipeVocabulary[number]): readonly string[] | undefined {
+  return "values" in property ? property.values : undefined;
+}
+
+type CaptionPlacement = Pick<StudioInspectorFieldDeclaration, "domain" | "page" | "section">;
+
+function captionPlace(domain: "where" | "how" | "when", page: string, section: string): CaptionPlacement {
+  return {
+    domain,
+    page: { id: page, label: title(page) },
+    section: { id: section, label: title(section) },
+  };
+}
+
+const captionPlacement = new Map<string, CaptionPlacement>();
+function placeCaption(names: readonly string[], domain: "where" | "how" | "when", page: string, section: string): void {
+  for (const name of names) captionPlacement.set(name, captionPlace(domain, page, section));
+}
+
+placeCaption(["stack-order", "x", "y", "width", "height", "anchor-x", "anchor-y"], "where", "placement", "region");
+placeCaption([
+  "align", "block-align", "inline-size", "wrap", "max-lines", "max-words-per-line", "direction",
+  "line-height", "letter-spacing", "word-gap",
+], "where", "flow", "flow");
+placeCaption(["size", "kerning", "caps", "text-transform"], "how", "text", "typography");
+placeCaption([
+  "fill", "opacity", "gradient-from", "gradient-to", "gradient-angle", "stroke-color", "stroke-width", "shadow-color",
+  "shadow-opacity", "shadow-x", "shadow-y", "shadow-blur", "shadow-spread", "long-shadow-color", "long-shadow-opacity",
+  "long-shadow-distance", "long-shadow-angle", "glow-color", "glow-opacity", "glow-blur", "glow-spread",
+], "how", "paint", "base-paint");
+placeCaption([
+  "active-fill", "active-opacity", "active-gradient-from", "active-gradient-to", "active-gradient-angle",
+  "active-stroke-color", "active-stroke-width", "active-shadow-color", "active-shadow-opacity", "active-shadow-x",
+  "active-shadow-y", "active-shadow-blur", "active-shadow-spread", "active-long-shadow-color",
+  "active-long-shadow-opacity", "active-long-shadow-distance", "active-long-shadow-angle", "active-glow-color",
+  "active-glow-opacity", "active-glow-blur", "active-glow-spread",
+], "how", "paint", "active-paint");
+placeCaption([
+  "background", "border-color", "border-width", "padding", "radius", "cue-shadow-color", "cue-shadow-opacity",
+  "cue-shadow-x", "cue-shadow-y", "cue-shadow-blur", "cue-shadow-spread",
+], "how", "cue-box", "cue-box");
+placeCaption([
+  "underline", "underline-color", "underline-thickness", "underline-offset", "active-underline-color",
+  "active-underline-thickness", "active-underline-offset", "active-box-background", "active-box-border-color",
+  "active-box-border-width", "active-box-padding", "active-box-radius",
+], "how", "decoration", "decoration");
+placeCaption(["lead-frames", "tail-frames", "handoff"], "when", "cue", "envelope");
+placeCaption([
+  "cue-enter", "cue-enter-frames", "cue-enter-start-scale", "cue-exit", "cue-exit-frames",
+], "when", "cue", "cue");
+placeCaption([
+  "karaoke", "karaoke-transition", "active-underline", "active-box", "active-box-continuity", "active-box-enter",
+  "active-box-exit", "active-box-transition-frames", "atom-enter", "atom-enter-frames", "atom-exit", "atom-exit-frames",
+  "atom-reveal", "active-response", "active-response-frames", "active-scale", "slide-distance",
+], "when", "token", "token");
+placeCaption(["loop", "loop-target", "loop-period-frames", "loop-intensity"], "when", "loop", "loop");
+
+const captionColorProperties = new Set([
+  "fill", "gradient-from", "gradient-to", "stroke-color", "shadow-color", "long-shadow-color", "glow-color",
+  "active-fill", "active-gradient-from", "active-gradient-to", "active-stroke-color", "active-shadow-color",
+  "active-long-shadow-color", "active-glow-color", "background", "border-color", "cue-shadow-color", "underline-color",
+  "active-underline-color", "active-box-background", "active-box-border-color",
+]);
+const captionTextProperties = new Set(["loop"]);
+
+export const captionFineInspectorFields: readonly StudioInspectorFieldDeclaration[] = recipeVocabulary.map((property) => {
+  const placement = captionPlacement.get(property.name);
+  if (placement === undefined) throw new Error(`Caption Studio has no explicit Inspector declaration for ${property.name}.`);
+  const options = valuesFor(property);
+  return {
+    binding: `program.${property.name}`,
+    label: title(property.name),
+    ...placement,
+    summary: property.summary,
+    control: options !== undefined ? "select" : captionColorProperties.has(property.name) ? "color"
+      : captionTextProperties.has(property.name) ? "text" : "number",
+    ...(options === undefined ? {} : { options }),
+  };
+});
+
+function cueText(document: CaptionDocument | undefined, unitIds: readonly string[]): string {
+  if (document === undefined) return "";
+  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();
+}
+
+function projectCaption(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+  const schedule = requiredSurfaceValue(context, "schedule") as FineCaptionSchedule;
+  const document = requiredReferencedValue(context, "document", narrativeTypes.captionDocument) as CaptionDocument;
+  if (document.id !== schedule.documentId) throw new Error("Caption Studio Schedule belongs to another CaptionDocument.");
+  const rendered = new Map(context.generic().flatMap((entity) =>
+    entity.presentId === undefined ? [] : [[entity.presentId, entity] as const]));
+  return schedule.cues.map((cue): StudioEntityDraft => {
+    const base = rendered.get(cue.id);
+    const label = cueText(document, cue.units.map((unit) => unit.unitId));
+    const authoredId = context.placement?.id ?? cue.id;
+    return {
+      ...(base ?? {
+        id: `${context.track.outputRef}:entity:${cue.id}`,
+        authoredId: cue.id,
+        display: { title: "Caption", layers: [] },
+        startFrame: cue.visibleStartFrame,
+        endFrameExclusive: cue.visibleEndFrameExclusive,
+        stackOrder: 0,
+        presentId: cue.id,
+        renderIds: [cue.id],
+      }),
+      authoredId,
+      ...(context.placement === undefined ? {} : { elementRange: context.placement.range }),
+      display: {
+        title: "Caption",
+        layers: label.length === 0 ? [] : [textLayer(label)],
+      },
+      startFrame: cue.visibleStartFrame,
+      endFrameExclusive: cue.visibleEndFrameExclusive,
+      presentation: { entity: "caption-cue", chrome: "standard" },
+      parameterReferences: { program: cue.styleId },
+    };
+  });
+}
+
+export const captionFineStudioTrackCompanions: readonly StudioTrackCompanion[] = [
+  {
+    id: "track", role: "track",
+    output: { type: compositionTypes.visualTrack, surface: "track", modules: [captionFineModuleRef] },
+    family: "caption", tone: "magenta", icon: "captions",
+    bindings: [
+      {
+        name: "program",
+        recipe: { through: ["recipe"], bindings: recipeVocabulary.map(({ name }) => ({ name })) },
+      },
+    ],
+    inspector: captionFineInspectorFields,
+    requiredValues: ["schedule"], project: projectCaption,
+    lane: { heightPx: 48 },
+  },
+];

package/packages/cli/README.md

@@ -0,0 +1,51 @@
+# `@hypit/cli`
+
+Domain neutral commands for checking, planning, building and inspecting Hypit projects.
+
+The command engine receives one explicit `CliDistribution`. A distribution supplies the compiler,
+trusted bootstrap packages, source package discovery and its Runtime Host. The official video
+executable assembles the Local Runtime through `@hypit/video-cli`; another application may provide
+another Host without changing this package or pretending that a local Profile selected it.
+
+Source imports decide which language and component packages give the source meaning. A Local Runtime
+Profile separately selects Credential Stores and Endpoints allowed to execute work. The CLI does not
+invent targets, candidates or Provider choices.
+
+Human output is compact by default. `--json` emits a command-specific view rather than raw compiler,
+Runtime or Repository objects. `--verbose` adds operational detail; it never turns the command into
+an internal state dump.
+
+`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
+made by an earlier Build step, that direct graph edge stays symbolic until the file exists; the rest
+of the request is still shown. A complete request is resolved through the same Endpoint Registry as
+the Build, including the Endpoint's `supports` check.
+
+`pricing <run>` uses that selected Runtime to read Provider-owned rate material. The default report
+summarizes requests whose resolved Endpoint explicitly declares `pricing.kind: "local"` as having no
+Provider charge. Requests with missing pricing declarations, failed price reads, or unresolved or
+unsupported Endpoints remain visible. Names, model families and request parameters do not determine
+whether work is free.
+
+Matching capability, Endpoint and pricing material share one group. Each group shows shared request
+parameters once and preserves the counts and combinations of varying parameters. A Provider's optional
+document summary supplies the default rate display; otherwise the document itself is shown, or the
+declared pricing page when no document is available. Documents retain the Provider's fields, units and conditions. The CLI
+does not interpret formulas, infer upstream media properties, or calculate totals.
+
+All groups are shown by default. `--limit <count>` limits human groups after grouping; `--verbose`
+adds no-charge request details, full request names and original documents. JSON uses `hypit.cli-pricing@1`: `requestCount`
+and `noChargeRequestCount` describe the whole Run, while `groups[]` holds Provider selection facts,
+`requests[]` with known parameters and pending inputs, and `pricingDocuments[]` with source and data.
+JSON includes every group regardless of `--limit`; no-charge requests are included with `--verbose`.
+
+The implementation follows those same boundaries: `command.ts` defines the exact semantic command
+union, while argument parsing and option ownership live in `arguments.ts`; project Result
+browsing/export lives under `commands/results.ts`; Runtime,
+credential, package and deployment operations live under `commands/environment.ts`; active Build
+observation is read-only code in `observation.ts`; and human rendering is separate from the explicit
+machine-view union. `main.ts` resolves project and selected Runtime context separately from parsed
+syntax, then routes these command groups. Result commands do not consult or construct a Runtime,
+and the generic CLI cannot silently choose a Result Repository or a Provider-specific login
+flow.

package/packages/cli/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@hypit/cli",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hypit/build-result": "workspace:*",
+    "@hypit/build-result-kit": "workspace:*",
+    "@hypit/compiler-node": "workspace:*",
+    "@hypit/component-kit": "workspace:*",
+    "@hypit/core": "workspace:*",
+    "@hypit/driver-node": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/package-loader-node": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/run": "workspace:*",
+    "@hypit/runtime": "workspace:*",
+    "@hypit/runtime-host-node": "workspace:*",
+    "@hypit/source": "workspace:*",
+    "@hypit/validation": "workspace:*",
+    "@hypit/workspace": "workspace:*",
+    "typescript": "5.9.3"
+  },
+  "devDependencies": {
+    "@hypit/markup": "workspace:*",
+    "@hypit/run-markup": "workspace:*",
+    "@hypit/workspace-fs-node": "workspace:*"
+  }
+}