@hypit/hypit 0.0.1 → 0.1.1

package/packages/provider-xiaomi-mimo/src/provider.ts

@@ -0,0 +1,214 @@
+import { defineEndpointPackage } from "@hypit/endpoint-kit";
+import type { EndpointInvocationContext } from "@hypit/endpoint-kit";
+import {
+  generationTypes,
+  sealGeneratedAudioSet,
+} from "@hypit/generation";
+import type { GenerationMediaValue, GenerationRequest } from "@hypit/generation";
+import type { CanonicalValue, CapabilityRef } from "@hypit/protocol";
+import { credentialRef } from "@hypit/runtime";
+import type { CredentialRef } from "@hypit/runtime";
+
+export const xiaomiMimoProviderModuleRef = { name: "@hypit/provider-xiaomi-mimo", version: "1" } as const;
+const mimoModelModule = { name: "@hypit/mimo-speech", version: "1" } as const;
+const modelNames = ["mimo-v2.5-tts-voicedesign", "mimo-v2.5-tts-voiceclone"] as const;
+type Model = typeof modelNames[number];
+
+const capabilities = Object.fromEntries(modelNames.map((name) => [name, {
+  module: mimoModelModule,
+  name,
+}])) as Readonly<Record<Model, CapabilityRef>>;
+
+type Fetch = typeof globalThis.fetch;
+
+export type CreateXiaomiMimoProviderOptions = {
+  readonly instance?: string;
+  readonly pool?: string;
+  readonly apiBaseUrl?: string;
+  readonly apiKey?: CredentialRef;
+  readonly defaultConcurrency?: number;
+  readonly requestTimeoutMs?: number;
+  readonly maxResponseBytes?: number;
+  readonly maxVoiceReferenceBase64Bytes?: number;
+  readonly fetch?: Fetch;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function positiveInteger(value: number, subject: string): number {
+  assert(Number.isSafeInteger(value) && value > 0, `${subject} must be a positive integer`);
+  return value;
+}
+
+function normalizeBaseUrl(value: string): string {
+  const url = new URL(value);
+  assert(url.protocol === "https:" || url.hostname === "localhost" || url.hostname === "127.0.0.1",
+    "Xiaomi MiMo apiBaseUrl must use HTTPS or loopback");
+  return url.href.replace(/\/$/u, "");
+}
+
+function request(value: CanonicalValue, model: Model): GenerationRequest {
+  const result = value as unknown as GenerationRequest;
+  assert(result.ports !== null && typeof result.ports === "object", "Xiaomi MiMo request has no ports");
+  const allowed = model === "mimo-v2.5-tts-voicedesign"
+    ? new Set(["text", "voiceDescription"])
+    : new Set(["text", "instruction", "voiceReference"]);
+  assert(Object.keys(result.ports).every((name) => allowed.has(name)),
+    `${model} request contains an unsupported port`);
+  return result;
+}
+
+function scalar(req: GenerationRequest, model: Model, name: string, required = true): string | undefined {
+  const values = req.ports[name];
+  if (values === undefined) {
+    if (required) throw new Error(`${model} requires ${name}`);
+    return undefined;
+  }
+  assert(values.length === 1 && typeof values[0] === "string", `${model} ${name} must contain one string`);
+  return values[0];
+}
+
+function credential(context: EndpointInvocationContext): string {
+  const value = context.credentials.apiKey?.secret;
+  assert(value !== undefined && value.length > 0, "Xiaomi MiMo API key is unavailable");
+  return value;
+}
+
+async function readVoiceReference(
+  context: EndpointInvocationContext,
+  req: GenerationRequest,
+  maxBase64Bytes: number,
+): Promise<string> {
+  const values = req.ports.voiceReference;
+  assert(values?.length === 1, "MiMo Voice Clone requires exactly one voiceReference");
+  const value = values[0] as GenerationMediaValue;
+  assert(value.role === "audio", "MiMo Voice Clone voiceReference must be audio");
+  const supported = new Set(["audio/mpeg", "audio/mp3", "audio/wav", "audio/x-wav"]);
+  assert(supported.has(value.artifact.mediaType), "Xiaomi MiMo accepts only MP3 or WAV voice references");
+  const encodedSize = 4 * Math.ceil(value.artifact.size / 3);
+  assert(encodedSize <= maxBase64Bytes,
+    `MiMo voice reference exceeds the configured ${maxBase64Bytes}-byte Base64 limit`);
+  const bytes = await context.resources.get(value.artifact.resource);
+  assert(bytes !== undefined, `MiMo voice reference ${value.artifact.resource} is unavailable`);
+  assert(bytes.byteLength === value.artifact.size, "MiMo voice reference size differs from its BlobRef");
+  const mediaType = value.artifact.mediaType === "audio/x-wav"
+    ? "audio/wav"
+    : value.artifact.mediaType === "audio/mp3" ? "audio/mpeg" : value.artifact.mediaType;
+  const encoded = Buffer.from(bytes).toString("base64");
+  assert(Buffer.byteLength(encoded, "utf8") <= maxBase64Bytes,
+    `MiMo voice reference exceeds the configured ${maxBase64Bytes}-byte Base64 limit`);
+  return `data:${mediaType};base64,${encoded}`;
+}
+
+function parseAudio(text: string, maxAudioBytes: number): Uint8Array {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    throw new Error("Xiaomi MiMo returned invalid JSON");
+  }
+  const root = raw as { choices?: Array<{ message?: { audio?: { data?: unknown } } }> };
+  const data = root.choices?.[0]?.message?.audio?.data;
+  assert(typeof data === "string" && data.length > 0, "Xiaomi MiMo returned no audio data");
+  assert(data.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/u.test(data),
+    "Xiaomi MiMo returned malformed Base64 audio");
+  const bytes = Uint8Array.from(Buffer.from(data, "base64"));
+  assert(bytes.byteLength > 0, "Xiaomi MiMo returned empty audio");
+  assert(bytes.byteLength <= maxAudioBytes, "Xiaomi MiMo audio exceeds the configured limit");
+  return bytes;
+}
+
+async function limitedResponseText(response: Response, maxBytes: number): Promise<string> {
+  const announced = response.headers.get("content-length");
+  if (announced !== null) {
+    const size = Number(announced);
+    assert(Number.isSafeInteger(size) && size >= 0, "Xiaomi MiMo returned invalid Content-Length");
+    assert(size <= maxBytes, "Xiaomi MiMo response exceeds the configured limit");
+  }
+  const reader = response.body?.getReader();
+  if (reader === undefined) {
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    assert(bytes.byteLength <= maxBytes, "Xiaomi MiMo response exceeds the configured limit");
+    return Buffer.from(bytes).toString("utf8");
+  }
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  while (true) {
+    const item = await reader.read();
+    if (item.done) break;
+    size += item.value.byteLength;
+    if (size > maxBytes) {
+      await reader.cancel();
+      throw new Error("Xiaomi MiMo response exceeds the configured limit");
+    }
+    chunks.push(item.value);
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  chunks.forEach((chunk) => { bytes.set(chunk, offset); offset += chunk.byteLength; });
+  return Buffer.from(bytes).toString("utf8");
+}
+
+export function createXiaomiMimoProvider(options: CreateXiaomiMimoProviderOptions) {
+  const apiBaseUrl = normalizeBaseUrl(options.apiBaseUrl ?? "https://api.xiaomimimo.com/v1");
+  const requestTimeoutMs = positiveInteger(options.requestTimeoutMs ?? 180_000, "requestTimeoutMs");
+  const maxResponseBytes = positiveInteger(options.maxResponseBytes ?? 64 * 1024 * 1024, "maxResponseBytes");
+  const maxVoiceReferenceBase64Bytes = positiveInteger(
+    options.maxVoiceReferenceBase64Bytes ?? 10_000_000,
+    "maxVoiceReferenceBase64Bytes",
+  );
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const endpointCapabilities = modelNames.map((model) => ({
+    capability: capabilities[model],
+    returns: generationTypes.audioSet,
+    lifecycle: "immediate" as const,
+    handler: async (context: EndpointInvocationContext) => {
+      const req = request(context.need.constraints, model);
+      const text = scalar(req, model, "text")!;
+      const messages: Array<{ role: "user" | "assistant"; content: string }> = [];
+      const audio: Record<string, CanonicalValue> = { format: "wav" };
+      if (model === "mimo-v2.5-tts-voicedesign") {
+        messages.push({ role: "user", content: scalar(req, model, "voiceDescription")! });
+      } else {
+        const instruction = scalar(req, model, "instruction", false);
+        if (instruction !== undefined) messages.push({ role: "user", content: instruction });
+        audio.voice = await readVoiceReference(context, req, maxVoiceReferenceBase64Bytes);
+      }
+      messages.push({ role: "assistant", content: text });
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(new Error("Xiaomi MiMo request timed out")), requestTimeoutMs);
+      let response: Response;
+      let responseText: string;
+      try {
+        response = await fetcher(`${apiBaseUrl}/chat/completions`, {
+          method: "POST",
+          headers: { "content-type": "application/json", "api-key": credential(context) },
+          body: JSON.stringify({ model, messages, audio }),
+          signal: controller.signal,
+        });
+        responseText = await limitedResponseText(response, maxResponseBytes);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (!response.ok) throw new Error(`Xiaomi MiMo returned HTTP ${response.status}: ${responseText.slice(0, 300)}`);
+      const bytes = parseAudio(responseText, maxResponseBytes);
+      const artifact = await context.resources.put(bytes, "audio/wav");
+      const result = sealGeneratedAudioSet({ audios: [artifact] });
+      return { value: { kind: "inline" as const, value: result as unknown as CanonicalValue } };
+    },
+  }));
+
+  return defineEndpointPackage({
+    module: xiaomiMimoProviderModuleRef,
+    facet: "speech",
+    instance: options.instance ?? "xiaomi-mimo.default",
+    pool: options.pool ?? options.instance ?? "xiaomi-mimo.default",
+    pricing: { kind: "page", url: "https://mimo.mi.com/docs/en-US/pricing" },
+    credentials: { apiKey: options.apiKey ?? credentialRef("env", "MIMO_API_KEY") },
+    credentialInputs: { apiKey: { label: "Xiaomi MiMo API key" } },
+    defaultConcurrency: options.defaultConcurrency ?? 2,
+    capabilities: endpointCapabilities,
+  });
+}

package/packages/ranking/README.md

@@ -0,0 +1,67 @@
+# `@hypit/ranking`
+
+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.
+
+Ranking boards that follow the argument of a video: introduce an item, give its verdict, and retain
+its place while the next item is discussed. Its Surface binds the performance's semantic time or
+authored time; the board consumes projected timing, Frames, Styles, fonts, text and optional icons or sound.
+
+| Form | Temporal behavior |
+| --- | --- |
+| `TierBoard` | Place icons into authored tiers. Each non-preset item has a reveal Window; its settled placement persists. |
+| `Column` | Place labeled rows at explicit ranks. Each non-preset row has a reveal Window; preset rows are already settled. |
+| `TopThree` | Stage up to three items from activation Instants and an explicit terminal Instant. |
+
+The board's outer Window owns its lifetime. Item reveal Windows must fit within it and be disjoint
+where the selected schedule requires succession. Ending a reveal does not remove its settled result.
+`preset` supplies initial state and needs no reveal event.
+
+## Bind the ranking to the target Script
+
+This excerpt assumes the Script, SemanticTrack, Canvas, Frame and Style have been declared:
+
+```svml
+<import as="ranking" from="@hypit/ranking@1"/>
+
+<ranking:Column id="priorities" semantic={speech.semantic} canvas={vertical}
+  frame={layout.ranking} during={story.segment.ranking} style={ranking-style}>
+  <ranking:ColumnItem rank="1" label="Winner" during={story.selection.winner}/>
+  <ranking:ColumnItem rank="2" preset="true" label="Already placed"/>
+</ranking:Column>
+```
+
+Choose `winner` to cover the phrase whose delivery stages this reveal. When that performance changes
+length, the projected Window follows the phrase. Style defines how the reveal and settling use that
+Window. TopThree instead accepts item `at` projections and a board `terminal` projection; a Moment
+can supply the intended trigger.
+
+Each board publishes `.schedule`, `.program` and `.visual`. Optional normalized `appear-sound` or
+`move-sound` inputs add `.audio` where that form supports them. Include the wanted visual and audio
+outputs as peers in Film. Labels can be literal or graph Text; Styles are typed SVS Recipes with
+exact fonts. Use `hypit vocabulary @hypit/ranking --tag Column` (or another declared tag) for its
+attributes, children, outputs and configured example.
+
+## Read it as a semantic component example
+
+The following files are included in the Distribution and show how the responsibilities connect:
+
+| File | What to learn from it |
+| --- | --- |
+| [surface.ts](src/surface.ts) | `rankingSurface` resolves author inputs, projects the outer and item times through `createTemporalWindowProjection` / `createTemporalInstantProjection`, and retains the returned drafts and references. |
+| [fragment.ts](src/fragment.ts) | `createRankingFragment` receives ProgramSpace and wires typed content, time, layout and Style inputs into finite operations. |
+| [schedule.ts](src/schedule.ts) | Compute reveal, activation and settled spans from the projected times. |
+| [component.ts](src/component.ts) and [render.ts](src/render.ts) | Build the ranking program and produce picture and optional sound from that schedule. |
+| [manifest.ts](src/manifest.ts) and [activation.ts](src/activation.ts) | Publish Types, Producers, Surface vocabulary and package contributions. |
+| [Ranking Companion](../ranking-studio/src/index.ts) | Read the same program, present persistent rows and activation lanes, and connect edits to actual Source inputs. |
+
+A project component can use these relationships with its own behavior. External TypeScript uses
+`@hypit/hypit/author-kit`, `@hypit/hypit/temporal-markup` and the appropriate `@hypit/hypit/*` domain APIs; the official
+implementation's `@hypit/*` imports are internal workspace spellings. Copy the relevant idea into
+the project's own package, with its own Module identity, instead of editing the installed Ranking.
+
+The Companion uses published values and temporal lineage, so a visible row and its reveal handle can
+represent different spans. Moving the authored semantic boundary changes the shared event and its
+consumers; editing a Style changes its appearance. [Studio Adapter](../studio-adapter/README.md)
+contains a minimal project Companion and the exact presentation/editing interface.

package/packages/ranking/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@hypit/ranking",
+  "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/program-space": "workspace:*",
+    "@hypit/protocol": "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/core": "workspace:*"
+  }
+}

package/packages/ranking/preview/Column.svg

@@ -0,0 +1,29 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="274" height="392" viewBox="0 0 274 392" fill="none">
+  <!-- A lightweight SVG approximation of three settled Column rows.
+       Geometry follows the real Column recipe: 112px cells, 18px column gap,
+       12px row gap, 16px outer padding, 8px rank radius and 18px icon radius. -->
+  <g transform="translate(16 16)">
+    <rect width="112" height="112" rx="8" fill="#FF3F56"/>
+    <path d="M125 0L125 618L226 522L5 522L5 700L361 700L361 0Z" fill="#FFFFFF" transform="translate(44.714 74.9) scale(.054 -.054)"/>
+    <rect x="130" width="112" height="112" rx="18" fill="#5B65C9"/>
+    <circle cx="186" cy="56" r="27" fill="none" stroke="#FFFFFF" stroke-width="10"/>
+    <circle cx="186" cy="56" r="7" fill="#FFFFFF"/>
+    <circle cx="215" cy="28" r="7" fill="#FFFFFF"/>
+  </g>
+
+  <g transform="translate(16 140)">
+    <rect width="112" height="112" rx="8" fill="#FFA72D"/>
+    <path d="M28 0L28 145L281 379Q305 402 316.5 419Q328 436 332 449.5Q336 463 336 475Q336 501 319 515.5Q302 530 268 530Q237 530 209 513.5Q181 497 165 465L-13 554Q25 626 101 671Q177 716 290 716Q373 716 437 689Q501 662 537 613Q573 564 573 497Q573 463 564.5 429Q556 395 530 357.5Q504 320 453 274L263 101L226 183L589 183L589 0Z" fill="#FFFFFF" transform="translate(39.584 75.332) scale(.054 -.054)"/>
+    <rect x="130" width="112" height="112" rx="18" fill="#279CA8"/>
+    <path d="M160 36h52v12h-52zM160 53h38v12h-38zM160 70h52v12h-52z" fill="#FFFFFF"/>
+    <path d="m202 53 17 6-17 6V53Z" fill="#FFFFFF"/>
+  </g>
+
+  <g transform="translate(16 264)">
+    <rect width="112" height="112" rx="8" fill="#EADC2A"/>
+    <path d="M270 -16Q198 -16 124 0Q50 16 -6 47L74 221Q119 195 168.5 182.5Q218 170 262 170Q302 170 327.5 183.5Q353 197 353 224Q353 247 334 259.5Q315 272 270 272L177 272L177 417L358 601L379 522L30 522L30 700L552 700L552 555L371 371L258 435L320 435Q452 435 521 376Q590 317 590 224Q590 164 556.5 109Q523 54 452.5 19Q382 -16 270 -16Z" fill="#FFFFFF" transform="translate(39.422 74.9) scale(.054 -.054)"/>
+    <rect x="130" width="112" height="112" rx="18" fill="#C96254"/>
+    <circle cx="174" cy="56" r="22" fill="none" stroke="#FFFFFF" stroke-width="10"/>
+    <circle cx="202" cy="56" r="22" fill="none" stroke="#FFFFFF" stroke-width="10"/>
+  </g>
+</svg>

package/packages/ranking/preview/TierBoard.svg

@@ -0,0 +1,36 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="274" height="392" viewBox="0 0 274 392" fill="none">
+  <!-- A compact crop of the real TierBoard: one continuous square-edged
+       table, original row paint and typography, and icons inside its dark
+       content column. The 24px side gutters remain visible when repeated. -->
+  <g>
+    <path d="M24 16H137V136H24Z" fill="#EE5F52"/>
+    <path d="M24 136H137V256H24Z" fill="#F0A04C"/>
+    <path d="M24 256H137V376H24Z" fill="#F0C84D"/>
+    <path d="M137 16H250V376H137Z" fill="#2B2B30"/>
+
+    <g fill="#2C2C2C" font-family="Inter,Arial,sans-serif" font-size="36" font-weight="400" text-anchor="middle">
+      <text x="80.5" y="88">S</text>
+      <text x="80.5" y="208">A</text>
+      <text x="80.5" y="328">B</text>
+    </g>
+
+    <g>
+      <rect x="145" y="28" width="96" height="96" rx="12" fill="#5B65C9"/>
+      <circle cx="193" cy="76" r="26" fill="#FFFFFF" fill-opacity=".16"/>
+      <path d="M186 59L210 76L186 93Z" fill="#FFFFFF"/>
+
+      <rect x="145" y="148" width="96" height="96" rx="12" fill="#279CA8"/>
+      <path d="M164 176H208V185H164ZM164 191H197V200H164ZM164 206H208V215H164Z" fill="#FFFFFF"/>
+      <path d="M201 190L217 196L201 202Z" fill="#FFFFFF"/>
+
+      <rect x="145" y="268" width="96" height="96" rx="12" fill="#C96254"/>
+      <circle cx="185" cy="316" r="19" fill="none" stroke="#FFFFFF" stroke-width="8"/>
+      <circle cx="207" cy="316" r="19" fill="none" stroke="#FFFFFF" stroke-width="8"/>
+    </g>
+
+    <g stroke="#111315" stroke-width="3">
+      <path d="M24 136H250M24 256H250M137 16V376"/>
+      <rect x="24" y="16" width="226" height="360"/>
+    </g>
+  </g>
+</svg>

package/packages/ranking/src/activation.ts

@@ -0,0 +1,38 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+  decodeColumnStyleSurface,
+  decodeColumnSurface,
+  decodeTierBoardStyleSurface,
+  decodeTierBoardSurface,
+  decodeTopThreeStyleSurface,
+  decodeTopThreeSurface,
+  rankingComponent,
+  rankingManifest,
+  rankingMarkupSurfaces,
+  rankingModuleRef,
+} from "./index.js";
+
+const facets = [
+  ["tier-style", decodeTierBoardStyleSurface],
+  ["column-style", decodeColumnStyleSurface],
+  ["top-three-style", decodeTopThreeStyleSurface],
+  ["tier", decodeTierBoardSurface],
+  ["column", decodeColumnSurface],
+  ["top-three", decodeTopThreeSurface],
+] as const;
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{
+    manifest: rankingManifest,
+  }],
+  components: [rankingComponent],
+  hostFacets: facets.map(([surface, handler]) => createMarkupSurfaceHostFacet({
+    module: rankingModuleRef,
+    declaration: rankingMarkupSurfaces.find((item) => item.name === surface)!,
+    handler,
+  })),
+};
+
+export default hypitPackage;