@hypit/hypit 0.0.1 → 0.1.0

package/packages/fonts-open/src/surface.ts

@@ -0,0 +1,239 @@
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { basename as fileName } from "node:path";
+
+import {
+  assertFontArtifactRef,
+  assertFontStackRef,
+  mediaTypes,
+} from "@hypit/media";
+import type { FontArtifactRef, FontStackRef } from "@hypit/media";
+import type { StructuredElement, StructuredSurfaceHandler } from "@hypit/markup";
+import { resolveNodePackageResource } from "@hypit/package-loader-node";
+
+import {
+  openFontFamilies,
+  openFontFamilyNames,
+} from "./catalog.js";
+import type {
+  OpenFontFamily,
+  OpenFontFamilyName,
+  OpenFontStyle,
+} from "./catalog.js";
+
+function resolveFontPackageFile(packageName: string, path: string): string {
+  try {
+    return resolveNodePackageResource(packageName, path, { from: import.meta.url });
+  } catch (error) {
+    const version = packageName === "@infolektuell/noto-color-emoji" ? "0.2.0" : "5.3.0";
+    throw new Error(
+      `${packageName} is needed by this authored font. Install it once with: hypit packages install ${packageName}@${version}`,
+      { cause: error },
+    );
+  }
+}
+
+function attributes(
+  element: StructuredElement,
+  required: readonly string[],
+  optional: readonly string[] = [],
+): void {
+  const names = Object.keys(element.attributes);
+  const allowed = new Set([...required, ...optional]);
+  if (required.some((name) => element.attributes[name] === undefined)
+    || names.some((name) => !allowed.has(name))) {
+    const suffix = optional.length === 0 ? "" : `, with optional ${optional.join(", ")}`;
+    throw new Error(`${element.name} requires exactly ${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 string`);
+  return value.trim();
+}
+
+type RequestedFace = {
+  readonly familyName: OpenFontFamilyName;
+  readonly family: OpenFontFamily;
+  readonly weight: number;
+  readonly style: OpenFontStyle;
+};
+
+function requestedFace(element: StructuredElement): RequestedFace {
+  const familyName = stringAttribute(element, "family") as OpenFontFamilyName;
+  if (!openFontFamilyNames.includes(familyName)) {
+    throw new Error(`${element.name}.family must be one of ${openFontFamilyNames.join(", ")}`);
+  }
+  const family: OpenFontFamily = openFontFamilies[familyName];
+  const weight = Number(stringAttribute(element, "weight"));
+  const validWeight = family.kind === "static" || family.kind === "static-split" || family.kind === "external-split"
+    ? family.weights.includes(weight)
+    : Number.isSafeInteger(weight) && weight >= family.minimumWeight && weight <= family.maximumWeight;
+  if (!validWeight) throw new Error(`${element.name}.weight is unavailable for ${familyName}`);
+  const style = stringAttribute(element, "style") as OpenFontStyle;
+  if (!(family.styles as readonly OpenFontStyle[]).includes(style)) {
+    throw new Error(`${element.name}.style is unavailable for ${familyName}`);
+  }
+  return { familyName, family, weight, style };
+}
+
+function oneFile(
+  family: OpenFontFamily & { readonly fileStem: string },
+  weight: number,
+  style: OpenFontStyle,
+): string {
+  const filename = family.kind === "static"
+    ? `${family.fileStem}-${weight}-${style}.woff2`
+    : `${family.fileStem}-${style}.woff2`;
+  return resolveFontPackageFile(family.packageName, `files/${filename}`);
+}
+
+function splitFiles(
+  family: OpenFontFamily & { readonly kind: "variable-split" | "static-split" | "external-split" },
+  weight: number,
+  style: OpenFontStyle,
+): readonly { readonly path: string; readonly unicodeRange: string }[] {
+  const css = family.kind === "variable-split"
+    ? family.css
+    : family.kind === "external-split"
+      ? family.css
+      : `${weight}${style === "italic" ? "-italic" : ""}.css`;
+  const cssPath = resolveFontPackageFile(family.packageName, css);
+  const contents = readFileSync(cssPath, "utf8");
+  return [...contents.matchAll(/@font-face\s*\{([\s\S]*?)\}/gu)].map((match) => {
+    const body = match[1]!;
+    const file = /src:\s*url\((?:['"])?\.\/files\/([^)'";]+\.woff2)(?:['"])?\)/u.exec(body)?.[1];
+    const unicodeRange = /unicode-range:\s*([^;]+);/u.exec(body)?.[1]?.replace(/\s+/gu, "");
+    if (file === undefined || unicodeRange === undefined) {
+      throw new Error(`${family.packageName}/${css} contains an unsupported @font-face`);
+    }
+    return { path: resolveFontPackageFile(family.packageName, `files/${file}`), unicodeRange };
+  });
+}
+
+async function materializeFace(
+  request: RequestedFace,
+  element: StructuredElement,
+  resolveAsset: Parameters<StructuredSurfaceHandler>[0]["resolveAsset"],
+): Promise<FontArtifactRef> {
+  const files = request.family.kind === "variable-split" || request.family.kind === "static-split"
+    || request.family.kind === "external-split"
+    ? splitFiles(request.family, request.weight, request.style)
+    : [{ path: oneFile(request.family, request.weight, request.style) }];
+  const resolvedSources: FontArtifactRef["sources"] = await Promise.all(files.map(async (file) => {
+    const bytes = Uint8Array.from(await readFile(file.path));
+    // `require.resolve` answers in the platform's own separator, and this name goes into the
+    // asset's provenance. Splitting on "/" left the whole absolute path standing in for the file
+    // name wherever that separator is a backslash, which put a machine's directory layout inside
+    // an identity that is supposed to name a font file and nothing else.
+    const basename = fileName(file.path);
+    const resolved = await resolveAsset({
+      from: `package:@hypit/fonts-open/${request.familyName}/${basename}`,
+      mediaType: "font/woff2",
+      bytes,
+      range: element.range,
+    });
+    return {
+      artifact: resolved.artifact,
+      ...("unicodeRange" in file ? { unicodeRange: file.unicodeRange } : {}),
+    };
+  }));
+  const byArtifact = new Map<string, FontArtifactRef["sources"][number]>();
+  for (const source of resolvedSources) {
+    const existing = byArtifact.get(source.artifact.resource);
+    if (existing === undefined) {
+      byArtifact.set(source.artifact.resource, source);
+      continue;
+    }
+    if (existing.unicodeRange === undefined || source.unicodeRange === undefined) continue;
+    byArtifact.set(source.artifact.resource, {
+      artifact: existing.artifact,
+      unicodeRange: `${existing.unicodeRange},${source.unicodeRange}`,
+    });
+  }
+  const font: FontArtifactRef = {
+    sources: [...byArtifact.values()],
+    weight: request.weight,
+    style: request.style,
+  };
+  assertFontArtifactRef(font, `${element.name}.${request.familyName}`);
+  return font;
+}
+
+function localName(name: string): string {
+  const colon = name.lastIndexOf(":");
+  return colon < 0 ? name : name.slice(colon + 1);
+}
+
+function emptyChildren(element: StructuredElement): void {
+  if (element.children.some((child) => child.kind === "element" || child.value.trim())) {
+    throw new Error(`${element.name} does not accept children`);
+  }
+}
+
+export const decodeOpenFontFaceSurface: StructuredSurfaceHandler = async ({ element, resolveAsset }) => {
+  attributes(element, ["id", "family", "weight", "style"]);
+  emptyChildren(element);
+  const id = stringAttribute(element, "id");
+  const font = await materializeFace(requestedFace(element), element, resolveAsset);
+  return {
+    records: [{
+      id,
+      type: mediaTypes.fontArtifact,
+      value: { kind: "inline", value: font },
+      range: element.range,
+    }],
+    components: [],
+    fragments: [],
+  };
+};
+
+/**
+ * Compact exact-font-stack authoring. Emoji stays explicit but no longer requires a separate Face
+ * declaration and Fallback reference for every Style.
+ */
+export const decodeOpenFontStackSurface: StructuredSurfaceHandler = async ({ element, resolveAsset }) => {
+  attributes(element, ["id", "family", "weight", "style"], ["emoji"]);
+  const id = stringAttribute(element, "id");
+  const faces: FontArtifactRef[] = [await materializeFace(requestedFace(element), element, resolveAsset)];
+
+  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, ["family", "weight", "style"]);
+    emptyChildren(child);
+    faces.push(await materializeFace(requestedFace(child), child, resolveAsset));
+  }
+
+  const emoji = element.attributes.emoji;
+  if (emoji !== undefined) {
+    if (emoji !== "color" && emoji !== "mono") {
+      throw new Error(`${element.name}.emoji must be color or mono`);
+    }
+    const familyName: OpenFontFamilyName = emoji === "color" ? "noto-color-emoji" : "noto-emoji";
+    const family = openFontFamilies[familyName];
+    faces.push(await materializeFace({
+      familyName,
+      family,
+      weight: 400,
+      style: "normal",
+    }, element, resolveAsset));
+  }
+
+  const stack: FontStackRef = { faces };
+  assertFontStackRef(stack, `${element.name}.${id}`);
+  return {
+    records: [{
+      id,
+      type: mediaTypes.fontStack,
+      value: { kind: "inline", value: stack },
+      range: element.range,
+    }],
+    components: [],
+    fragments: [],
+  };
+};

package/packages/generation/README.md

@@ -0,0 +1,19 @@
+# `@hypit/hypit/generation`
+
+Provider-neutral generated-media contracts shared by exact image, video and audio model packages.
+
+External Model and Provider packages import this public subpath from the `@hypit/hypit` Distribution.
+It gives both sides the same request and result vocabulary without a dependency between their
+implementations. `sealGenerationPortTable` describes a model's inputs; `GenerationWireMapping` and
+`compileWireRequest` can translate those inputs to one Provider's documented wire fields.
+`selectWireModelForRequest` applies the same route selection without resolving media bytes. During
+planning, a Provider may add the model-port names already attached as future graph inputs; the
+selector does not inspect graph structure or interpret media roles.
+
+The package owns `GenerationRequest`, `GeneratedImageSet` and `GeneratedVideoSet` identities,
+schemas, validators and graph facets. Generated sets are atomic Products: a Provider persists the
+returned bytes in an ResourceStore and returns typed Blob references rather than transient URLs.
+
+This package does not choose a model, Provider, credential, queue or retry policy. Model packages
+declare exact request Capabilities; Endpoint packages such as `@hypit/provider-kie` implement those
+Capabilities in a selected Runtime Profile.

package/packages/generation/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@hypit/generation",
+  "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/protocol": "workspace:*",
+    "@hypit/text": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/driver-node": "workspace:*",
+    "@hypit/validation": "workspace:*"
+  }
+}

package/packages/generation/src/activation.ts

@@ -0,0 +1,9 @@
+import { generationComponent, generationManifest } from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: generationManifest }],
+  components: [generationComponent],
+};
+
+export default hypitPackage;

package/packages/generation/src/component.ts

@@ -0,0 +1,77 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+
+import {
+  verifyGeneratedAudioSet,
+  verifyGeneratedImageSet,
+  verifyGeneratedVideoSet,
+} from "./identity.js";
+import { generationProducers, generationTypes } from "./manifest.js";
+
+function inline(value: { readonly kind: string; readonly value?: unknown }, subject: string): unknown {
+  if (value.kind !== "inline") throw new Error(`${subject} must be inline`);
+  return value.value;
+}
+
+function primary(
+  value: { readonly kind: string; readonly value?: unknown },
+  kind: "audio" | "image" | "video",
+): import("@hypit/protocol").BlobRef {
+  const label = kind === "audio" ? "Audio" : kind === "image" ? "Image" : "Video";
+  const content = inline(value, `Generated${label}Set`) as {
+    readonly images?: readonly import("@hypit/protocol").BlobRef[];
+    readonly videos?: readonly import("@hypit/protocol").BlobRef[];
+    readonly audios?: readonly import("@hypit/protocol").BlobRef[];
+  };
+  const selected = kind === "audio"
+    ? content.audios?.[0]
+    : kind === "image" ? content.images?.[0] : content.videos?.[0];
+  if (selected === undefined) throw new Error(`Generated ${kind} set has no primary artifact`);
+  return selected;
+}
+
+/** Host-side semantic refinements for the shared generated-media contracts. */
+export const generationComponent = {
+  producers: [
+    {
+      producer: generationProducers.primaryAudio,
+      handler: ({ inputs }) => ({
+        outputs: { audio: primary(inputs.set!.value, "audio") },
+        needs: {},
+      }),
+    },
+    {
+      producer: generationProducers.primaryImage,
+      handler: ({ inputs }) => ({
+        outputs: { image: primary(inputs.set!.value, "image") },
+        needs: {},
+      }),
+    },
+    {
+      producer: generationProducers.primaryVideo,
+      handler: ({ inputs }) => ({
+        outputs: { video: primary(inputs.set!.value, "video") },
+        needs: {},
+      }),
+    },
+  ],
+  validators: [
+    {
+      type: generationTypes.audioSet,
+      handler: ({ value }) => {
+        verifyGeneratedAudioSet(inline(value, "GeneratedAudioSet"));
+      },
+    },
+    {
+      type: generationTypes.imageSet,
+      handler: ({ value }) => {
+        verifyGeneratedImageSet(inline(value, "GeneratedImageSet"));
+      },
+    },
+    {
+      type: generationTypes.videoSet,
+      handler: ({ value }) => {
+        verifyGeneratedVideoSet(inline(value, "GeneratedVideoSet"));
+      },
+    },
+  ],
+} satisfies ComponentPackage;

package/packages/generation/src/identity.ts

@@ -0,0 +1,80 @@
+import {
+  canonicalize,
+  isResourceId,
+} from "@hypit/protocol";
+import type { BlobRef } from "@hypit/protocol";
+
+import type {
+  GeneratedAudioSet,
+  GeneratedAudioSetContent,
+  GeneratedImageSet,
+  GeneratedImageSetContent,
+  GeneratedVideoSet,
+  GeneratedVideoSetContent,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function plainObject(value: unknown, subject: string): Record<string, unknown> {
+  assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} must be an object`);
+  return value as Record<string, unknown>;
+}
+
+export function assertGenerationBlobRef(
+  value: unknown,
+  mediaPrefix?: "image/" | "video/" | "audio/",
+): asserts value is BlobRef {
+  const object = plainObject(value, "Generation artifact");
+  assert(object.kind === "blob", "Generation artifact must be a BlobRef");
+  assert(typeof object.resource === "string" && isResourceId(object.resource), "Generation artifact resource is invalid");
+  assert(Number.isSafeInteger(object.size) && (object.size as number) >= 0, "Generation artifact size is invalid");
+  assert(typeof object.mediaType === "string" && object.mediaType.length > 0, "Generation artifact mediaType is invalid");
+  if (mediaPrefix !== undefined) {
+    assert(object.mediaType.startsWith(mediaPrefix), `Generation artifact must have ${mediaPrefix} media`);
+  }
+}
+
+/** Canonical request value; Core supplies the enclosing Need identity. */
+export function sealGenerationRequest<T extends object>(
+  content: T,
+): T {
+  return canonicalize(content) as unknown as T;
+}
+
+export function sealGeneratedImageSet(content: GeneratedImageSetContent): GeneratedImageSet {
+  assert(content.images.length > 0, "Generated image set is empty");
+  content.images.forEach((artifact) => assertGenerationBlobRef(artifact, "image/"));
+  return canonicalize(content) as unknown as GeneratedImageSet;
+}
+
+export function verifyGeneratedImageSet(value: unknown): asserts value is GeneratedImageSet {
+  const object = plainObject(value, "Generated image set") as unknown as GeneratedImageSet;
+  assert(Array.isArray(object.images) && object.images.length > 0, "Generated image set is empty");
+  object.images.forEach((artifact) => assertGenerationBlobRef(artifact, "image/"));
+}
+
+export function sealGeneratedVideoSet(content: GeneratedVideoSetContent): GeneratedVideoSet {
+  assert(content.videos.length > 0, "Generated video set is empty");
+  content.videos.forEach((artifact) => assertGenerationBlobRef(artifact, "video/"));
+  return canonicalize(content) as unknown as GeneratedVideoSet;
+}
+
+export function verifyGeneratedVideoSet(value: unknown): asserts value is GeneratedVideoSet {
+  const object = plainObject(value, "Generated video set") as unknown as GeneratedVideoSet;
+  assert(Array.isArray(object.videos) && object.videos.length > 0, "Generated video set is empty");
+  object.videos.forEach((artifact) => assertGenerationBlobRef(artifact, "video/"));
+}
+
+export function sealGeneratedAudioSet(content: GeneratedAudioSetContent): GeneratedAudioSet {
+  assert(content.audios.length > 0, "Generated audio set is empty");
+  content.audios.forEach((artifact) => assertGenerationBlobRef(artifact, "audio/"));
+  return canonicalize(content) as unknown as GeneratedAudioSet;
+}
+
+export function verifyGeneratedAudioSet(value: unknown): asserts value is GeneratedAudioSet {
+  const object = plainObject(value, "Generated audio set") as unknown as GeneratedAudioSet;
+  assert(Array.isArray(object.audios) && object.audios.length > 0, "Generated audio set is empty");
+  object.audios.forEach((artifact) => assertGenerationBlobRef(artifact, "audio/"));
+}

package/packages/generation/src/index.ts

@@ -0,0 +1,79 @@
+export { generationComponent } from "./component.js";
+export {
+  assertGenerationBlobRef,
+  sealGeneratedAudioSet,
+  sealGeneratedImageSet,
+  sealGeneratedVideoSet,
+  sealGenerationRequest,
+  verifyGeneratedImageSet,
+  verifyGeneratedAudioSet,
+  verifyGeneratedVideoSet,
+} from "./identity.js";
+export { generationManifest, generationModuleRef, generationProducers, generationTypes } from "./manifest.js";
+export {
+  assertMappingCoversPorts,
+  compileWireRequest,
+  mappingSupportsRequest,
+  selectWireModel,
+  selectWireModelForRequest,
+} from "./mapping.js";
+export type {
+  GenerationArtifactUrlResolver,
+  GenerationFieldMapping,
+  GenerationWireMapping,
+  GenerationWireRequest,
+  GenerationWireRoute,
+} from "./mapping.js";
+export {
+  assertGenerationPortTable,
+  generationPort,
+  isMediaPort,
+  sealGenerationPortTable,
+} from "./ports.js";
+export type {
+  GenerationItemRequirement,
+  GenerationMediaPort,
+  GenerationMediaPortKind,
+  GenerationMediaRole,
+  GenerationMediaValue,
+  GenerationPort,
+  GenerationPortItemField,
+  GenerationPortKind,
+  GenerationPortRequirement,
+  GenerationPortScalarKind,
+  GenerationPortTable,
+  GenerationPortValue,
+  GenerationScalarPort,
+} from "./ports.js";
+export {
+  bindGenerationMedia,
+  bindGenerationText,
+  finalizeGenerationRequestDraft,
+  mediaBindingSchemaFromPort,
+  portsObjectSchema,
+  requestDraftSchemaFromPorts,
+  requestSchemaFromPorts,
+  sealGenerationMediaBinding,
+  sealGenerationPortRequest,
+  sealGenerationRequestDraft,
+  verifyGenerationMediaBinding,
+  verifyPortsAgainstTable,
+  verifyRequestDraftAgainstPorts,
+  verifyRequestAgainstPorts,
+} from "./request.js";
+export type {
+  GenerationMediaBinding,
+  GenerationPortSubset,
+  GenerationRequest,
+  GenerationRequestDraft,
+} from "./request.js";
+export {
+  generatedImageSetSchema,
+  generatedAudioSetSchema,
+  generatedVideoSetSchema,
+  generationBlobRefSchema,
+  generationResourceSchema,
+  generationObjectSchema,
+  generationPromptSchema,
+} from "./schema.js";
+export type * from "./types.js";

package/packages/generation/src/manifest.ts

@@ -0,0 +1,65 @@
+import {
+  artifactDependency,
+  artifactTypes,
+} from "@hypit/artifact";
+import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
+
+import { generatedAudioSetSchema, generatedImageSetSchema, generatedVideoSetSchema } from "./schema.js";
+
+export const generationModuleRef = { name: "@hypit/generation", version: "1" } as const;
+export const generationTypes = {
+  audioSet: { module: generationModuleRef, name: "GeneratedAudioSet" },
+  imageSet: { module: generationModuleRef, name: "GeneratedImageSet" },
+  videoSet: { module: generationModuleRef, name: "GeneratedVideoSet" },
+} satisfies Record<string, TypeRef>;
+
+export const generationProducers = {
+  primaryAudio: { module: generationModuleRef, name: "select-primary-audio" },
+  primaryImage: { module: generationModuleRef, name: "select-primary-image" },
+  primaryVideo: { module: generationModuleRef, name: "select-primary-video" },
+} satisfies Record<string, ProducerRef>;
+
+export const generationManifest: ModuleManifest = {
+  format: "hypit.module@1",
+  name: generationModuleRef.name,
+  version: generationModuleRef.version,
+  dependencies: [artifactDependency],
+  types: [
+    {
+      name: generationTypes.audioSet.name,
+    },
+    {
+      name: generationTypes.imageSet.name,
+    },
+    {
+      name: generationTypes.videoSet.name,
+    },
+  ],
+  capabilities: [],
+  producers: [
+    {
+      name: generationProducers.primaryAudio.name,
+      inputs: [{ name: "set", type: generationTypes.audioSet }],
+      outputs: [{ name: "audio", type: artifactTypes.blob }],
+      needs: [],
+    },
+    {
+      name: generationProducers.primaryImage.name,
+      inputs: [{ name: "set", type: generationTypes.imageSet }],
+      outputs: [{
+        name: "image",
+        type: artifactTypes.blob,
+      }],
+      needs: [],
+    },
+    {
+      name: generationProducers.primaryVideo.name,
+      inputs: [{ name: "set", type: generationTypes.videoSet }],
+      outputs: [{
+        name: "video",
+        type: artifactTypes.blob,
+      }],
+      needs: [],
+    },
+  ],
+};