@hypit/hypit 0.0.1 → 0.1.1

package/packages/cli/src/source-discovery.ts

@@ -0,0 +1,150 @@
+import { readFile, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+
+import { authorFrontendsFromHostFacets, prepareAuthorSource } from "@hypit/elaborator";
+import type { AuthorFrontend } from "@hypit/elaborator";
+import { physicalPackageName, resolveNodePackageSource } from "@hypit/package-loader-node";
+import type { LogicalPackageAddress, LoadedPackage } from "@hypit/package-loader-node";
+import { modulePackageAbi } from "@hypit/protocol";
+import { prepareRunSource, runFragmentHostAbi, runFrontendsFromHostFacets } from "@hypit/run";
+import type { RunFrontend } from "@hypit/run";
+import { parseSourceHeader, sourceFrontendPackageAbi } from "@hypit/source";
+
+function isWithin(root: string, path: string): boolean {
+  const relation = relative(root, path);
+  return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
+}
+
+function selectedPackage(request: string): string {
+  const version = request.lastIndexOf("@");
+  if (version <= 0) throw new Error(`Package request ${request} must end in @version`);
+  return physicalPackageName(request);
+}
+
+function addressKey(value: LogicalPackageAddress): string {
+  return `${value.abi}\u0000${value.name}`;
+}
+
+/**
+ * Discover the package requirements reachable from a self-described Source closure.
+ * A Distribution supplies only its bootstrap Frontends; every further language,
+ * Module and Run Fragment is resolved from package-owned logical offers.
+ */
+export async function discoverSourcePackages(
+  sourcePath: string,
+  options: {
+    readonly workspaceRoot?: string;
+    readonly packageRoot?: string;
+    readonly distributionPackageRoot?: string;
+    readonly packages?: readonly LoadedPackage[];
+    readonly bootstrapAuthorFrontends?: readonly AuthorFrontend[];
+    readonly bootstrapRunFrontends?: readonly RunFrontend[];
+  } = {},
+): Promise<{ readonly selected: readonly string[]; readonly logical: readonly LogicalPackageAddress[] }> {
+  const canonicalSource = await realpath(resolve(sourcePath));
+  const root = await realpath(resolve(options.workspaceRoot ?? dirname(canonicalSource)));
+  const packageRoot = resolve(options.packageRoot ?? root);
+  if (!isWithin(root, canonicalSource)) throw new Error(`Source ${canonicalSource} is outside workspace root ${root}`);
+
+  const packages = options.packages ?? [];
+  const authorFrontends = [
+    ...(options.bootstrapAuthorFrontends ?? []).map((frontend) => ({ frontend, physical: undefined as string | undefined })),
+    ...packages.flatMap((item) => authorFrontendsFromHostFacets(item.contribution.hostFacets ?? [])
+      .map((frontend) => ({ frontend, physical: item.specifier as string | undefined }))),
+  ];
+  const runFrontends = [
+    ...(options.bootstrapRunFrontends ?? []).map((frontend) => ({ frontend, physical: undefined as string | undefined })),
+    ...packages.flatMap((item) => runFrontendsFromHostFacets(item.contribution.hostFacets ?? [])
+      .map((frontend) => ({ frontend, physical: item.specifier as string | undefined }))),
+  ];
+  const selected = new Set<string>();
+  const logical = new Map<string, LogicalPackageAddress>();
+  const visited = new Set<string>();
+  const moduleOwners = new Map<string, string>();
+  const fragmentOwners = new Map<string, string>();
+  for (const item of packages) {
+    for (const module of item.contribution.modules ?? []) {
+      for (const request of [`${module.manifest.name}@${module.manifest.version}`, ...(module.specifiers ?? [])]) {
+        moduleOwners.set(request, item.specifier);
+      }
+    }
+    for (const facet of item.contribution.hostFacets ?? []) {
+      if (facet.abi !== runFragmentHostAbi) continue;
+      for (const request of facet.offers ?? []) fragmentOwners.set(request, item.specifier);
+    }
+  }
+
+  const requireLogical = (address: LogicalPackageAddress, physical: string | undefined): void => {
+    logical.set(addressKey(address), address);
+    selected.add(physical ?? selectedPackage(address.name));
+  };
+  const resolveImportedSource = (
+    importer: string,
+    importerRoot: string,
+    request: string,
+  ): { readonly source: string; readonly root: string } => {
+    if (request.startsWith("./") || request.startsWith("../")) {
+      return { source: resolve(dirname(importer), request), root: importerRoot };
+    }
+    const located = resolveNodePackageSource(request, {
+      from: importer,
+      workspaceRoots: [packageRoot],
+      ...(options.distributionPackageRoot === undefined
+        ? {}
+        : { distributionRoots: [options.distributionPackageRoot] }),
+      externalRoots: [],
+      allowExternal: false,
+    });
+    return { source: located.source, root: located.root };
+  };
+  const discover = async (path: string, sourceRoot: string): Promise<void> => {
+    const canonical = await realpath(path);
+    const canonicalRoot = await realpath(sourceRoot);
+    if (!isWithin(canonicalRoot, canonical)) {
+      throw new Error(`Source ${canonical} is outside its source root ${canonicalRoot}`);
+    }
+    if (visited.has(canonical)) return;
+    visited.add(canonical);
+    const text = await readFile(canonical, "utf8");
+    const name = relative(canonicalRoot, canonical);
+    const header = parseSourceHeader(name, text);
+    const authors = authorFrontends.filter((item) => item.frontend.id === header.using);
+    const runs = runFrontends.filter((item) => item.frontend.id === header.using);
+    if (authors.length + runs.length > 1) throw new Error(`Source Frontend ${header.using} is ambiguously provided`);
+    if (authors.length + runs.length === 0) {
+      requireLogical({ abi: sourceFrontendPackageAbi, name: header.using }, undefined);
+      return;
+    }
+    if (authors.length === 1) {
+      const owner = authors[0]!;
+      if (owner.physical !== undefined) {
+        requireLogical({ abi: sourceFrontendPackageAbi, name: owner.frontend.id }, owner.physical);
+      }
+      const discovery = await owner.frontend.discover(prepareAuthorSource({ id: canonical, name, text }));
+      for (const request of discovery.modules) {
+        requireLogical({ abi: modulePackageAbi, name: request }, moduleOwners.get(request));
+      }
+      for (const child of discovery.sources) {
+        const imported = resolveImportedSource(canonical, canonicalRoot, child.from);
+        await discover(imported.source, imported.root);
+      }
+      return;
+    }
+    const owner = runs[0]!;
+    if (owner.physical !== undefined) {
+      requireLogical({ abi: sourceFrontendPackageAbi, name: owner.frontend.id }, owner.physical);
+    }
+    const discovery = await owner.frontend.discover(prepareRunSource({ id: canonical, name, text }));
+    for (const item of discovery.imports) {
+      requireLogical({ abi: runFragmentHostAbi, name: item.from }, fragmentOwners.get(item.from));
+    }
+    const imported = resolveImportedSource(canonical, canonicalRoot, discovery.author.source);
+    await discover(imported.source, imported.root);
+  };
+
+  await discover(canonicalSource, root);
+  return {
+    selected: [...selected].sort(),
+    logical: [...logical.values()].sort((left, right) => addressKey(left).localeCompare(addressKey(right))),
+  };
+}

package/packages/cli/src/source-packages.ts

@@ -0,0 +1,91 @@
+import {
+  loadNodePackageSelection,
+} from "@hypit/package-loader-node";
+import type {
+  LoadedPackage,
+  LogicalPackageAddress,
+  NodePackageSelectionRequest,
+} from "@hypit/package-loader-node";
+import { modulePackageAbi } from "@hypit/protocol";
+
+import type { CliDistribution } from "./distribution.js";
+
+type DiscoveryOptions = {
+  readonly source: string;
+  readonly workspaceRoot?: string;
+  readonly packageRoot: string;
+  readonly distributionPackageRoot?: string;
+};
+
+function mergePackages(
+  ...groups: readonly (readonly LoadedPackage[])[]
+): readonly LoadedPackage[] {
+  return [...new Map(groups.flat().map((item) => [item.specifier, item])).values()];
+}
+
+async function discover(
+  distribution: CliDistribution,
+  options: DiscoveryOptions,
+  packages: readonly LoadedPackage[],
+) {
+  const selection = await distribution.discoverSourcePackages?.(options.source, {
+    ...(options.workspaceRoot === undefined ? {} : { workspaceRoot: options.workspaceRoot }),
+    packageRoot: options.packageRoot,
+    ...(options.distributionPackageRoot === undefined
+      ? {}
+      : { distributionPackageRoot: options.distributionPackageRoot }),
+    packages,
+  });
+  if (selection === undefined) throw new Error("this Distribution cannot discover Source packages");
+  return selection;
+}
+
+function offerCounts(packages: readonly LoadedPackage[]): ReadonlyMap<string, number> {
+  const counts = new Map<string, number>();
+  for (const item of packages) {
+    const offers = [
+      ...(item.contribution.modules ?? []).flatMap((module) => [
+        `${module.manifest.name}@${module.manifest.version}`,
+        ...(module.specifiers ?? []),
+      ].map((name) => ({ abi: modulePackageAbi, name }))),
+      ...(item.contribution.hostFacets ?? []).flatMap((facet) =>
+        (facet.offers ?? []).map((name) => ({ abi: facet.abi, name }))),
+    ];
+    for (const address of new Set(offers.map((offer) => `${offer.abi}\u0000${offer.name}`))) {
+      counts.set(address, (counts.get(address) ?? 0) + 1);
+    }
+  }
+  return counts;
+}
+
+function selectionSatisfied(
+  selection: NodePackageSelectionRequest,
+  packages: readonly LoadedPackage[],
+): boolean {
+  const installed = new Set(packages.map((item) => item.specifier));
+  const counts = offerCounts(packages);
+  return selection.selected.every((item) => installed.has(item))
+    && (selection.logical ?? []).every((address) => counts.get(`${address.abi}\u0000${address.name}`) === 1);
+}
+
+/** Load only the installed packages reached by recursive Frontend discovery. */
+export async function loadDiscoveredSourcePackages(
+  distribution: CliDistribution,
+  options: DiscoveryOptions,
+): Promise<readonly LoadedPackage[]> {
+  let packages = distribution.bootstrapPackages;
+  while (true) {
+    const selection = await discover(distribution, options, packages);
+    if (selectionSatisfied(selection, packages)) return packages;
+    const loaded = await loadNodePackageSelection(selection, options.packageRoot, {
+      ...(options.distributionPackageRoot === undefined
+        ? {}
+        : { fallbackRoots: [options.distributionPackageRoot] }),
+    });
+    const next = mergePackages(distribution.bootstrapPackages, loaded);
+    if (next.map((item) => item.specifier).join("\u0000") === packages.map((item) => item.specifier).join("\u0000")) {
+      throw new Error("Source package discovery did not satisfy its logical package requirements");
+    }
+    packages = next;
+  }
+}

package/packages/cli/src/view.ts

@@ -0,0 +1,228 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+import type {
+  BuildResultManifest,
+  BuildResultRepository,
+  RepositoryBuildResultOutputDescription,
+} from "@hypit/build-result";
+import { buildIdCreatedAt } from "@hypit/protocol";
+import type { TypeRef } from "@hypit/protocol";
+import type { BuildView } from "@hypit/runtime-host-node";
+
+export type PublicOutputKind = "scalar" | "resource" | "composite";
+
+export type CliOutputView = {
+  readonly name: string;
+  readonly type: string;
+  readonly kind: PublicOutputKind;
+  readonly target: boolean;
+  readonly highlighted: boolean;
+  readonly mediaType?: string;
+  readonly size?: number;
+};
+
+export type CliBuildSummary = {
+  readonly id: string;
+  readonly title?: string;
+  readonly createdAt: string;
+  readonly outcome: "complete" | "failed" | "cancelled";
+  readonly run?: string;
+  readonly targetCount: number;
+  readonly targets?: readonly string[];
+  readonly omittedTargets?: number;
+  readonly outputCount: number;
+};
+
+export type CliBuildResultView = {
+  readonly id: string;
+  readonly title?: string;
+  readonly note?: string;
+  readonly createdAt: string;
+  readonly finishedAt?: string;
+  readonly outcome: "open" | "complete" | "failed" | "cancelled";
+  readonly source: string;
+  readonly run?: string;
+  readonly targetCount: number;
+  readonly targets: readonly string[];
+  readonly omittedTargets?: number;
+  readonly outputs: readonly CliOutputView[];
+  readonly omittedOutputs?: number;
+  readonly failure?: string;
+  readonly operations?: BuildResultManifest["operations"];
+  readonly omittedOperations?: number;
+};
+
+export type CliBuildStatusView = {
+  readonly id: string;
+  readonly title?: string;
+  readonly work: {
+    readonly state: "unknown" | "submitting" | "working" | "done";
+    readonly outcome?: "complete" | "failed" | "cancelled";
+    readonly cancellationRequested?: boolean;
+    readonly stop?: BuildView["stop"];
+    readonly requests?: { readonly total: number; readonly completed: number };
+  };
+  readonly result: {
+    readonly state: "missing" | "open" | "complete" | "failed" | "cancelled" | "unavailable";
+    readonly outputCount?: number;
+  };
+  readonly attention?: { readonly message: string; readonly action?: string };
+  readonly operations?: readonly {
+    readonly id?: string;
+    readonly receipt?: { readonly id: string; readonly url?: string };
+    readonly endpoint: string;
+    readonly state: string;
+    readonly progress?: {
+      readonly phase: string;
+      readonly completed?: number;
+      readonly total?: number;
+      readonly unit?: string;
+    };
+    readonly failure?: { readonly code: string; readonly message: string };
+  }[];
+};
+
+export function cliTypeName(type: TypeRef): string {
+  return `${type.module.name}@${type.module.version}/${type.name}`;
+}
+
+export function projectPath(path: string, projectRoot: string): string {
+  const absolute = isAbsolute(path) ? resolve(path) : resolve(projectRoot, path);
+  const local = relative(resolve(projectRoot), absolute);
+  if (local.length === 0) return ".";
+  if (local === ".." || local.startsWith(`..${sep}`)) return path;
+  return local;
+}
+
+export function buildCreatedAtIso(build: string): string {
+  const createdAt = buildIdCreatedAt(build);
+  if (createdAt === undefined) throw new Error(`Build id ${build} has no submission time`);
+  return new Date(createdAt).toISOString();
+}
+
+export async function outputView(
+  repository: BuildResultRepository,
+  manifest: BuildResultManifest,
+  name: string,
+): Promise<CliOutputView> {
+  const output = await repository.describeOutput(manifest.id, name);
+  if (output === undefined) {
+    throw new Error(`Build Result ${manifest.id} Output ${name} cannot be resolved`);
+  }
+  return {
+    name,
+    type: cliTypeName(output.type),
+    kind: output.kind,
+    target: manifest.targets.includes(name),
+    highlighted: manifest.highlightedOutputs?.includes(name) === true,
+    ...(output.kind === "resource" ? {
+      mediaType: output.mediaType,
+      size: output.size,
+    } : {}),
+  };
+}
+
+function orderedOutputNames(manifest: BuildResultManifest): readonly string[] {
+  const names = Object.keys(manifest.outputs);
+  const highlighted = new Set(manifest.highlightedOutputs ?? []);
+  const targets = new Set(manifest.targets);
+  return names.sort((left, right) => {
+    const leftRank = highlighted.has(left) ? 0 : targets.has(left) ? 1 : 2;
+    const rightRank = highlighted.has(right) ? 0 : targets.has(right) ? 1 : 2;
+    return leftRank - rightRank || left.localeCompare(right);
+  });
+}
+
+function workState(view: BuildView | undefined, result: BuildResultManifest | undefined): CliBuildStatusView["work"]["state"] {
+  if (view === undefined) return result?.outcome === undefined ? "unknown" : "done";
+  if (view.activity === "submitting") return "submitting";
+  if (view.activity === "ready" || view.activity === "running" || view.activity === "waiting") return "working";
+  return "done";
+}
+
+export function buildStatusView(options: {
+  readonly id: string;
+  readonly runtime?: BuildView;
+  readonly result?: BuildResultManifest;
+  readonly resultReadError?: string;
+  readonly verbose?: boolean;
+  readonly operationLimit?: number;
+}): CliBuildStatusView {
+  const resultState = options.resultReadError !== undefined
+    ? "unavailable" as const
+    : options.result?.outcome ?? (options.result === undefined ? "missing" as const : "open" as const);
+  const issue = options.runtime?.issue;
+  return {
+    id: options.id,
+    ...(options.result?.title === undefined ? {} : { title: options.result.title }),
+    work: {
+      state: workState(options.runtime, options.result),
+      ...((options.runtime?.outcome ?? options.result?.outcome) === undefined
+        ? {}
+        : { outcome: options.runtime?.outcome ?? options.result!.outcome }),
+      ...(options.runtime?.cancellationRequested === true ? { cancellationRequested: true } : {}),
+      ...(options.runtime?.stop === undefined ? {} : { stop: options.runtime.stop }),
+      ...(options.runtime?.requests === undefined ? {} : { requests: options.runtime.requests }),
+    },
+    result: {
+      state: resultState,
+      ...(options.result === undefined ? {} : { outputCount: Object.keys(options.result.outputs).length }),
+    },
+    ...(issue === undefined && options.resultReadError === undefined ? {} : {
+      attention: issue !== undefined
+        ? {
+            message: issue.message,
+            ...(issue.scope === "result" ? { action: `hypit result finish ${options.id}` } : {}),
+          }
+        : { message: options.resultReadError! },
+    }),
+    ...(!options.verbose ? {} : {
+      operations: (options.runtime?.operations ?? options.result?.operations ?? [])
+        .filter((item) => item.status !== "completed")
+        .slice(0, options.operationLimit ?? 20)
+        .map((item) => ({
+          ...("operation" in item ? { id: item.operation } : item.id === undefined ? {} : { id: item.id }),
+          ...(item.receipt === undefined ? {} : { receipt: item.receipt }),
+          endpoint: item.endpoint,
+          state: item.status,
+          ...(item.progress === undefined ? {} : { progress: item.progress }),
+          ...(item.failure === undefined ? {} : { failure: {
+            code: item.failure.code,
+            message: item.failure.message,
+          } }),
+        })),
+    }),
+  };
+}
+
+export async function buildResultView(
+  repository: BuildResultRepository,
+  manifest: BuildResultManifest,
+  options: { readonly projectRoot: string; readonly output?: string; readonly limit: number },
+): Promise<CliBuildResultView> {
+  if (options.output !== undefined && manifest.outputs[options.output] === undefined) {
+    throw new Error(`Build Result ${manifest.id} has no public Output ${options.output}`);
+  }
+  const allNames = options.output === undefined ? orderedOutputNames(manifest) : [options.output];
+  const selected = allNames.slice(0, options.limit);
+  const outputs = await Promise.all(selected.map(async (name) =>
+    await outputView(repository, manifest, name)));
+  return {
+    id: manifest.id,
+    ...(manifest.title === undefined ? {} : { title: manifest.title }),
+    ...(manifest.note === undefined ? {} : { note: manifest.note }),
+    createdAt: buildCreatedAtIso(manifest.id),
+    ...(manifest.finishedAt === undefined ? {} : { finishedAt: new Date(manifest.finishedAt).toISOString() }),
+    outcome: manifest.outcome ?? "open",
+    source: projectPath(manifest.source.path, options.projectRoot),
+    ...(manifest.run === undefined ? {} : { run: projectPath(manifest.run.path, options.projectRoot) }),
+    targetCount: manifest.targets.length,
+    targets: manifest.targets.slice(0, options.limit),
+    ...(manifest.targets.length <= options.limit ? {} : { omittedTargets: manifest.targets.length - options.limit }),
+    outputs,
+    ...(selected.length === allNames.length ? {} : { omittedOutputs: allNames.length - selected.length }),
+    ...(manifest.failure === undefined ? {} : { failure: manifest.failure }),
+    ...(manifest.operations === undefined ? {} : { operations: manifest.operations.slice(0, options.limit) }),
+    ...((manifest.operations?.length ?? 0) <= options.limit ? {} : { omittedOperations: manifest.operations!.length - options.limit }),
+  };
+}

package/packages/comment-sticker/README.md

@@ -0,0 +1,41 @@
+# `@hypit/comment-sticker`
+
+The Track Surface accepts `semantic={speech.semantic}` or `space={animation}`. Semantic context
+resolves Script Selections and Moments; authored space supports clock-based animation. Shared `at`
+inputs accept a Moment or a time such as `2s`; `at` with `for` produces a Window where required.
+
+An author package for timed social-comment cards. It publishes an ordinary `VisualTrack` containing
+the cards' independently timed appearances.
+
+The author surface keeps the three independent concerns visible:
+
+- `SpatialFrame` owns placement and size;
+- an SVS Recipe plus an exact `FontStackRef` owns appearance and local motion;
+- the shared Temporal projection owns when an item exists.
+
+```xml
+<import as="copy" from="@hypit/text@1"/>
+
+<copy:Value id="comment-copy">This part finally made the idea click.</copy:Value>
+<copy:Value id="comment-author">@viewer</copy:Value>
+
+<comment:Style id="social-comment" recipe={styles.comment} font={fonts.ui}/>
+
+<comment:Track id="comments" canvas={video.canvas} semantic={speech.semantic}>
+  <comment:Sticker
+    id="opening-comment"
+    comment={comment-copy}
+    frame={layout.comment}
+    style={social-comment}
+    author={comment-author}
+    meta="Featured comment"
+    during="program"
+  />
+</comment:Track>
+```
+
+Body text remains the compact literal form. `comment`, `author`, `header` and `meta` also accept
+ordinary graph `Text` references; `comment={...}` is exclusive with body text. The Fragment builds
+one package-owned content value through explicit Text edges before temporal placement. `avatar` is
+an independent Artifact edge. Metadata is never fabricated: if `meta` is absent, no metadata row
+is rendered. Sound effects remain a separate Audio Track.

package/packages/comment-sticker/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@hypit/comment-sticker",
+  "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/artifact": "workspace:*",
+    "@hypit/component-kit": "workspace:*",
+    "@hypit/composition": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/media": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/program-space": "workspace:*",
+    "@hypit/semantic-track": "workspace:*",
+    "@hypit/spatial": "workspace:*",
+    "@hypit/svs": "workspace:*",
+    "@hypit/temporal": "workspace:*",
+    "@hypit/temporal-markup": "workspace:*",
+    "@hypit/text": "workspace:*",
+    "@hypit/markup": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/hyperframes": "workspace:*"
+  }
+}

package/packages/comment-sticker/src/activation.ts

@@ -0,0 +1,32 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+  commentStickerComponent,
+  commentStickerManifest,
+  commentStickerModuleRef,
+  decodeCommentStickerStyleSurface,
+  decodeCommentStickerTrackSurface,
+  commentStickerMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{
+    manifest: commentStickerManifest,
+  }],
+  components: [commentStickerComponent],
+  hostFacets: [
+    createMarkupSurfaceHostFacet({
+      module: commentStickerModuleRef,
+    declaration: commentStickerMarkupSurfaces.find((item) => item.name === "style")!,
+      handler: decodeCommentStickerStyleSurface,
+    }),
+    createMarkupSurfaceHostFacet({
+      module: commentStickerModuleRef,
+    declaration: commentStickerMarkupSurfaces.find((item) => item.name === "track")!,
+      handler: decodeCommentStickerTrackSurface,
+    }),
+  ],
+};
+
+export default hypitPackage;