@hypit/hypit 0.0.1 → 0.1.1

package/packages/script/src/surface.ts

@@ -0,0 +1,132 @@
+import { ScriptSyntaxError } from "./error.js";
+import {
+  captionDocumentValue,
+  narrativeDialogueTextValue,
+  narrativeSegmentExcerptValue,
+  narrativeMomentValue,
+  narrativeSelectionValue,
+  narrativeSpeechTextValue,
+  narrativeValue,
+} from "./narrative.js";
+import {
+  captionDocumentType,
+  narrativeExcerptType,
+  narrativeMomentType,
+  narrativeSelectionType,
+  narrativeType,
+} from "./manifest.js";
+import { textTypes } from "@hypit/text";
+import { parseScript } from "./parser.js";
+import type { ScriptSurfaceInput, ScriptSurfaceOutput } from "./types.js";
+
+const RECORD_ID = /^[a-z][a-z0-9_-]{0,63}$/u;
+
+function findClose(input: ScriptSurfaceInput): { readonly start: number; readonly end: number } {
+  const close = `</${input.tag}>`;
+  let cursor = input.contentStart;
+  while (cursor < input.source.length) {
+    if (input.source.startsWith("<!--", cursor)) {
+      const commentEnd = input.source.indexOf("-->", cursor + 4);
+      if (commentEnd < 0) {
+        throw new ScriptSyntaxError("SCRIPT_COMMENT", "Unclosed Script comment.", input.sourceName, cursor);
+      }
+      cursor = commentEnd + 3;
+      continue;
+    }
+    if (input.source.startsWith(close, cursor)) {
+      let slashes = 0;
+      for (let before = cursor - 1; before >= 0 && input.source[before] === "\\"; before -= 1) slashes += 1;
+      if (slashes % 2 === 0) return { start: cursor, end: cursor + close.length };
+    }
+    cursor += 1;
+  }
+  throw new ScriptSyntaxError(
+    "SCRIPT_SURFACE_UNCLOSED",
+    `Raw Surface <${input.tag}> is not closed.`,
+    input.sourceName,
+    input.openingStart,
+  );
+}
+
+export function decodeScriptSurface(input: ScriptSurfaceInput): ScriptSurfaceOutput {
+  const unknown = Object.keys(input.attributes).filter((name) => name !== "id");
+  if (unknown.length) {
+    throw new ScriptSyntaxError(
+      "SCRIPT_SURFACE_ATTRIBUTE",
+      `<${input.tag}> does not declare attribute "${unknown[0]}".`,
+      input.sourceName,
+      input.openingStart,
+    );
+  }
+  const rawId = input.attributes.id ?? "script";
+  if (typeof rawId !== "string" || !RECORD_ID.test(rawId)) {
+    throw new ScriptSyntaxError(
+      "SCRIPT_SURFACE_ID",
+      `<${input.tag}> id must be a canonical lower-case identifier.`,
+      input.sourceName,
+      input.openingStart,
+    );
+  }
+  const close = findClose(input);
+  const parsed = parseScript(
+    input.sourceName,
+    input.source.slice(input.contentStart, close.start),
+    input.contentStart,
+  );
+  const captionId = `${rawId}.caption`;
+  return {
+    nextOffset: close.end,
+    records: [
+      {
+        id: rawId,
+        type: narrativeType,
+        value: { kind: "inline", value: narrativeValue(parsed, rawId) },
+        range: { start: input.openingStart, end: close.end },
+      },
+      ...parsed.segments.map((segment) => ({
+        id: `${rawId}.segment.${segment.id}`,
+        type: narrativeExcerptType,
+        value: { kind: "inline" as const, value: narrativeSegmentExcerptValue(parsed, segment, rawId) },
+        range: segment.range,
+      })),
+      ...parsed.segments.flatMap((segment) => [
+        {
+          id: `${rawId}.segment.${segment.id}.dialogue`,
+          type: textTypes.text,
+          value: { kind: "inline" as const, value: narrativeDialogueTextValue(segment) },
+          range: segment.range,
+        },
+        {
+          id: `${rawId}.segment.${segment.id}.speech`,
+          type: textTypes.text,
+          value: { kind: "inline" as const, value: narrativeSpeechTextValue(segment) },
+          range: segment.range,
+        },
+      ]),
+      {
+        id: captionId,
+        type: captionDocumentType,
+        value: { kind: "inline" as const, value: captionDocumentValue(parsed, captionId, rawId) },
+        range: { start: input.openingStart, end: close.end },
+      },
+      ...parsed.selections.map((selection) => ({
+        id: `${rawId}.selection.${selection.id}`,
+        type: narrativeSelectionType,
+        value: { kind: "inline" as const, value: narrativeSelectionValue(selection, rawId) },
+        range: {
+          start: selection.open.range.start,
+          end: selection.close.range.end,
+        },
+      })),
+      ...parsed.moments.map((moment) => ({
+        id: `${rawId}.moment.${moment.id}`,
+        type: narrativeMomentType,
+        value: { kind: "inline" as const, value: narrativeMomentValue(moment, rawId) },
+        range: moment.range,
+      })),
+    ],
+    components: [],
+    fragments: [],
+    identities: [{ namespace: narrativeType, id: rawId }],
+  };
+}

package/packages/script/src/types.ts

@@ -0,0 +1,125 @@
+import type { CanonicalValue, SourceRange, StoredValue, TypeRef } from "@hypit/protocol";
+import type { CaptionWordAttribute, Narrative, NarrativeMoment, NarrativeSegment, NarrativeSelection, NarrativeToken, NarrativeTurn } from "@hypit/narrative";
+
+export type { CaptionWordAttribute, Narrative, SemanticAnchor } from "@hypit/narrative";
+
+export type Affinity = "left" | "right";
+
+/** Script-only source structure. Public Selection/Moment values expose only resolved anchors. */
+export type MarkerBoundary = {
+  readonly tokenIndex: number;
+  readonly structuralPosition: number;
+  readonly segmentId?: string;
+  readonly anchorId: string;
+};
+
+export type ParsedTextAtom = {
+  readonly kind: "text";
+  readonly speech: string;
+  readonly caption: string;
+  readonly tokenStart: number;
+  readonly tokenEndExclusive: number;
+  readonly range: SourceRange;
+};
+
+export type ParsedRoleAtom = {
+  readonly kind: "role";
+  readonly label: string;
+  readonly range: SourceRange;
+};
+
+export type ParsedAtom = ParsedTextAtom | ParsedRoleAtom;
+
+export type ParsedSegment = NarrativeSegment & {
+  /** Parser-local array position; omitted from the public Narrative value. */
+  readonly index: number;
+  readonly atoms: readonly ParsedAtom[];
+  readonly range: SourceRange;
+  /** Exact body range between the Segment tags, used only for source-preserving marker edits. */
+  readonly contentRange: SourceRange;
+  readonly selfClosing: boolean;
+};
+
+export type ParsedToken = NarrativeToken & {
+  /** Parser-local positions used to create stable source anchor ids; omitted from Narrative. */
+  readonly index: number;
+  readonly segmentTokenIndex: number;
+  readonly range: SourceRange;
+};
+export type ParsedTurn = NarrativeTurn & { readonly range: SourceRange };
+
+export type ParsedSelection = Omit<NarrativeSelection, "narrativeId"> & {
+  readonly open: { readonly affinity: Affinity; readonly boundary: MarkerBoundary; readonly range: SourceRange };
+  readonly close: { readonly affinity: Affinity; readonly boundary: MarkerBoundary; readonly range: SourceRange };
+};
+export type ParsedMoment = Omit<NarrativeMoment, "narrativeId"> & {
+  readonly affinity: Affinity;
+  readonly boundary: MarkerBoundary;
+  readonly range: SourceRange;
+};
+
+export type ParsedCaptionRegion = {
+  readonly id: string;
+  readonly display: string;
+  readonly segmentId: string;
+  readonly startToken: number;
+  readonly endTokenExclusive: number;
+  readonly kind: "identity" | "alias" | "hidden";
+  /** Flat word attributes authored on the display side; indices address displayWordSurfaces(display). */
+  readonly marks: readonly {
+    readonly displayIndex: number;
+    readonly attributes: readonly CaptionWordAttribute[];
+  }[];
+  readonly range: SourceRange;
+};
+
+export type ParsedNarrative = Omit<
+  Narrative,
+  "id" | "segments" | "tokens" | "turns" | "selections" | "moments"
+> & {
+  /** Exact Script body range, used only for source-preserving Program-boundary edits. */
+  readonly sourceRange: SourceRange;
+  readonly segments: readonly ParsedSegment[];
+  readonly tokens: readonly ParsedToken[];
+  readonly turns: readonly ParsedTurn[];
+  readonly selections: readonly ParsedSelection[];
+  readonly moments: readonly ParsedMoment[];
+  /** Script-private renderings used to emit independent public Text values. */
+  readonly serializations: {
+    readonly dialogue: string;
+    readonly speech: string;
+  };
+  readonly captionProjection: {
+    readonly text: string;
+    readonly regions: readonly ParsedCaptionRegion[];
+    readonly breaks: readonly { readonly tokenIndex: number; readonly range: SourceRange }[];
+  };
+};
+
+export type ScriptSurfaceRecordDraft = {
+  readonly id: string;
+  readonly type: TypeRef;
+  readonly value: StoredValue;
+  readonly range: SourceRange;
+};
+
+export type ScriptSurfaceInput = {
+  readonly sourceName: string;
+  readonly source: string;
+  readonly tag: string;
+  readonly openingStart: number;
+  readonly contentStart: number;
+  readonly attributes: Readonly<Record<string, string | CanonicalValue>>;
+};
+
+export type ScriptSurfaceOutput = {
+  readonly nextOffset: number;
+  readonly records: readonly ScriptSurfaceRecordDraft[];
+  /** Script is a record-only Surface; it cannot smuggle executable graph declarations. */
+  readonly components: readonly never[];
+  readonly fragments: readonly never[];
+  readonly identities: readonly {
+    readonly namespace: TypeRef;
+    readonly id: string;
+  }[];
+};

package/packages/script-studio/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@hypit/script-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/script": "workspace:*",
+    "@hypit/studio-adapter": "workspace:*"
+  }
+}

package/packages/script-studio/src/activation.ts

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

package/packages/script-studio/src/index.ts

@@ -0,0 +1,61 @@
+import { adjustScriptMoment, adjustScriptSelection, parseScript, scriptModuleRef } from "@hypit/script";
+import type { StudioScriptCompanion } from "@hypit/studio-adapter";
+
+export const scriptStudioCompanions: readonly StudioScriptCompanion[] = [{
+  id: "script",
+  match: { module: scriptModuleRef, surface: "script" },
+  observe(input) {
+    const narrativeId = input.attributes.id ?? "script";
+    if (typeof narrativeId !== "string" || narrativeId.length === 0) return undefined;
+    const closing = `</${input.tag}>`;
+    const closeEnd = input.nextOffset;
+    if (closeEnd === undefined) return undefined;
+    const end = closeEnd - closing.length;
+    if (end < input.contentStart || input.source.slice(end, closeEnd) !== closing) return undefined;
+    const parsed = parseScript(
+      input.sourceName,
+      input.source.slice(input.contentStart, end),
+      input.contentStart,
+    );
+    return {
+      narrativeId,
+      sourcePath: input.sourceName,
+      range: { start: input.openingStart, end: closeEnd },
+      content: { start: input.contentStart, end },
+      segments: parsed.segments.map((segment) => ({ id: segment.id, range: segment.range })),
+      selections: parsed.selections.map((selection) => ({
+        id: selection.id,
+        startAnchorId: selection.startAnchorId,
+        endAnchorId: selection.endAnchorId,
+        open: selection.open.range,
+        close: selection.close.range,
+      })),
+      moments: parsed.moments.map((moment) => ({
+        id: moment.id,
+        anchorId: moment.anchorId,
+        range: moment.range,
+      })),
+      tokens: parsed.tokens.map((token) => ({ id: token.id, range: token.range })),
+    };
+  },
+  adjust(input) {
+    const parsed = parseScript(input.sourceName, input.source);
+    return input.adjustment.kind === "selection"
+      ? adjustScriptSelection({
+          sourceName: input.sourceName,
+          source: input.source,
+          parsed,
+          adjustment: {
+            id: input.adjustment.id,
+            startAnchorId: input.adjustment.startAnchorId,
+            endAnchorId: input.adjustment.endAnchorId,
+          },
+        })
+      : adjustScriptMoment({
+          sourceName: input.sourceName,
+          source: input.source,
+          parsed,
+          adjustment: { id: input.adjustment.id, anchorId: input.adjustment.anchorId },
+        });
+  },
+}];

package/packages/seedance/README.md

@@ -0,0 +1,19 @@
+# `@hypit/seedance`
+
+Exact Seedance author model module. It owns the request schema and exactly three invocation Surfaces;
+it does not contain KIE credentials, HTTP code, queues, runtime routing or usage-specific Prompt assembly.
+
+The three model invocation shapes are deliberately separate:
+
+- `TextVideo`: Prompt only; this is the only shape that exposes Web Search.
+- `FrameVideo`: required first frame and optional last frame.
+- `ReferenceVideo`: one or more image, video or audio references within the model's port limits.
+
+All three preserve the remote result as one atomic `GeneratedVideoSet`, then expose its first ordered
+member as an ordinary `BlobArtifact`. Their prompt ports consume ordinary `Text`, so a Script projection,
+generic Text Template or third-party author module can feed them without becoming part of Seedance.
+
+`standard`, `fast`, `mini` and `2.5` select model variants independently of the invocation shape. Duration is
+the author's literal, in whole seconds inside the model's declared range; measure the spoken line first
+with `hypit measure` and write the number here. Nothing in the graph computes it, so a Build plan is
+complete before it starts.

package/packages/seedance/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@hypit/seedance",
+  "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/elaborator": "workspace:*",
+    "@hypit/generation": "workspace:*",
+    "@hypit/model-kit": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/text": "workspace:*",
+    "@hypit/markup": "workspace:*"
+  }
+}

package/packages/seedance/src/activation.ts

@@ -0,0 +1,38 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+  decodeSeedanceFrameVideoSurface,
+  decodeSeedanceReferenceVideoSurface,
+  decodeSeedanceTextVideoSurface,
+  seedanceComponent,
+  seedanceDefinition,
+  seedanceManifest,
+  seedanceModuleRef,
+  seedanceMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: seedanceManifest }],
+  components: [seedanceComponent],
+  hostFacets: [
+    seedanceDefinition.hostFacet,
+    createMarkupSurfaceHostFacet({
+      module: seedanceModuleRef,
+    declaration: seedanceMarkupSurfaces.find((item) => item.name === "text-video")!,
+      handler: decodeSeedanceTextVideoSurface,
+    }),
+    createMarkupSurfaceHostFacet({
+      module: seedanceModuleRef,
+    declaration: seedanceMarkupSurfaces.find((item) => item.name === "frame-video")!,
+      handler: decodeSeedanceFrameVideoSurface,
+    }),
+    createMarkupSurfaceHostFacet({
+      module: seedanceModuleRef,
+    declaration: seedanceMarkupSurfaces.find((item) => item.name === "reference-video")!,
+      handler: decodeSeedanceReferenceVideoSurface,
+    }),
+  ],
+};
+
+export default hypitPackage;

package/packages/seedance/src/fragment.ts

@@ -0,0 +1,46 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGraphFragment } from "@hypit/elaborator";
+import { generationProducers } from "@hypit/generation";
+import { createExactModelPrimaryGenerationFragment } from "@hypit/model-kit";
+import type { ExactModelEndpoint, ExactModelMediaInput, ExactModelTextInput } from "@hypit/model-kit";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+/**
+ * Keep the remote GeneratedVideoSet atomic, then deterministically expose its
+ * primary video as an ordinary BlobArtifact for downstream media programs.
+ */
+export function createSeedanceGenerationFragment(endpoint: ExactModelEndpoint) {
+  return sealGraphFragment({
+    inputs: [{ name: "request", type: endpoint.requestType }],
+    operations: [
+      {
+        id: "generate",
+        producer: endpoint.producer,
+        inputs: { request: input("request") },
+        result: { kind: "need", name: "generation" },
+      },
+      {
+        id: "select-primary-video",
+        producer: generationProducers.primaryVideo,
+        inputs: { set: operation("generate") },
+        result: { kind: "output", name: "video" },
+      },
+    ],
+    exports: [{
+      name: "video",
+      type: artifactTypes.blob,
+      root: operation("select-primary-video"),
+    }],
+  });
+}
+
+/** Request assembly used by author Surfaces whose media references may be runtime outputs. */
+export function createSeedanceAssembledGenerationFragment(
+  endpoint: ExactModelEndpoint,
+  mediaInputs: readonly ExactModelMediaInput[] = [],
+  textInputs: readonly ExactModelTextInput[] = [],
+) {
+  return createExactModelPrimaryGenerationFragment(endpoint, mediaInputs, textInputs);
+}