@hypit/hypit 0.0.1 → 0.1.0

package/packages/screen-overlay/src/surface.ts

@@ -0,0 +1,90 @@
+import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { spatialTypes } from "@hypit/spatial";
+import type { StructuredElement, StructuredSurfaceHandler, SurfaceComponentDraft, SurfaceRecordDraft, SurfaceResolvedReference, MarkupAttributeValue } from "@hypit/markup";
+import { createTemporalWindowProjection, temporalWindowAttributeNames } from "@hypit/temporal-markup";
+import { createScreenOverlayFragment } from "./fragment.js";
+import { screenOverlayTypes } from "./manifest.js";
+import { sealScreenOverlayHeader, sealScreenOverlayItemSpec } from "./program.js";
+import type { ScreenOverlayComponent } from "./types.js";
+
+const TIMING = temporalWindowAttributeNames;
+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 allowed(element: StructuredElement, names: readonly string[]): void {
+  const permit = new Set(names); const unexpected = Object.keys(element.attributes).filter((name) => !permit.has(name));
+  if (unexpected.length > 0) throw new Error(`${element.name} has unsupported attributes ${unexpected.join(", ")}.`);
+}
+function text(element: StructuredElement, name: string, fallback?: string): string {
+  const value = element.attributes[name]; if (value === undefined && fallback !== undefined) return fallback;
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${element.name}.${name} must be text.`); return value.trim();
+}
+function optionalText(element: StructuredElement, name: string): string | undefined {
+  const value = element.attributes[name]; if (value === undefined) return undefined;
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${element.name}.${name} must be text.`); return value.trim();
+}
+function ref(raw: MarkupAttributeValue | undefined, label: string, expected: SurfaceResolvedReference["type"], resolve: (path: string) => SurfaceResolvedReference | undefined): SurfaceResolvedReference {
+  if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);
+  const value = resolve(raw.path); if (value === undefined || !sameType(value.type, expected)) throw new Error(`${label} has the wrong Type.`); return value;
+}
+function numeric(element: StructuredElement, name: string, fallback?: number): number {
+  const raw = optionalText(element, name); if (raw === undefined && fallback !== undefined) return fallback;
+  const value = Number(raw); if (!Number.isFinite(value)) throw new Error(`${element.name}.${name} must be numeric.`); return value;
+}
+function integer(element: StructuredElement, name: string, fallback?: number): number {
+  const value = numeric(element, name, fallback); if (!Number.isSafeInteger(value)) throw new Error(`${element.name}.${name} must be an integer.`); return value;
+}
+function colors(element: StructuredElement, name: string): string[] {
+  const values = text(element, name).split(",").map((value) => value.trim()).filter(Boolean);
+  if (values.length === 0) throw new Error(`${element.name}.${name} requires colors.`); return values;
+}
+function content(element: StructuredElement): { readonly value: ScreenOverlayComponent; readonly attributes: readonly string[] } {
+  const name = element.name.split(":").at(-1);
+  switch (name) {
+    case "Flash": return { value: { kind: "flash", color: text(element, "color"), intensity: numeric(element, "intensity"), attackFrames: integer(element, "attack"), holdFrames: integer(element, "hold"), decayFrames: integer(element, "decay") }, attributes: ["color", "intensity", "attack", "hold", "decay"] };
+    case "ColorWash": return { value: { kind: "color-wash", color: text(element, "color"), opacity: numeric(element, "opacity") }, attributes: ["color", "opacity"] };
+    case "Vignette": return { value: { kind: "vignette", center: { x: numeric(element, "center-x"), y: numeric(element, "center-y") }, radius: { x: numeric(element, "radius-x"), y: numeric(element, "radius-y") }, softness: numeric(element, "softness"), color: text(element, "color"), opacity: numeric(element, "opacity") }, attributes: ["center-x", "center-y", "radius-x", "radius-y", "softness", "color", "opacity"] };
+    case "ScanLines": return { value: { kind: "scan-lines", spacingPx: numeric(element, "spacing"), thicknessPx: numeric(element, "thickness"), angleDeg: numeric(element, "angle"), opacity: numeric(element, "opacity"), travelPx: numeric(element, "travel") }, attributes: ["spacing", "thickness", "angle", "opacity", "travel"] };
+    case "DirectionalMatte": return { value: { kind: "directional-matte", angleDeg: numeric(element, "angle"), coverage: numeric(element, "coverage"), feather: numeric(element, "feather"), color: text(element, "color"), opacity: numeric(element, "opacity"), progress: { from: numeric(element, "from"), to: numeric(element, "to") } }, attributes: ["angle", "coverage", "feather", "color", "opacity", "from", "to"] };
+    case "WhipVeil": return { value: { kind: "whip-veil", direction: text(element, "direction") as "left", widthPx: numeric(element, "width"), softnessPx: numeric(element, "softness"), travelPx: numeric(element, "travel"), opacity: numeric(element, "opacity") }, attributes: ["direction", "width", "softness", "travel", "opacity"] };
+    case "GlitchVeil": return { value: { kind: "glitch-veil", bars: integer(element, "bars"), colors: colors(element, "colors"), opacity: numeric(element, "opacity"), travelPx: numeric(element, "travel"), seed: integer(element, "seed") }, attributes: ["bars", "colors", "opacity", "travel", "seed"] };
+    case "Grain": return { value: { kind: "grain", amount: numeric(element, "amount"), grainSizePx: numeric(element, "size"), chroma: text(element, "chroma") as "monochrome", motionRatePxPerFrame: numeric(element, "motion-rate"), seed: integer(element, "seed") }, attributes: ["amount", "size", "chroma", "motion-rate", "seed"] };
+    case "LightLeak": return { value: { kind: "light-leak", colors: colors(element, "colors"), angleDeg: numeric(element, "angle"), softness: numeric(element, "softness"), travelPx: numeric(element, "travel"), intensity: numeric(element, "intensity"), seed: integer(element, "seed") }, attributes: ["colors", "angle", "softness", "travel", "intensity", "seed"] };
+    case "Bokeh": return { value: { kind: "bokeh", amount: numeric(element, "amount"), sizeMinPx: numeric(element, "min-size"), sizeMaxPx: numeric(element, "max-size"), color: text(element, "color"), warmth: numeric(element, "warmth"), driftPx: numeric(element, "drift"), seed: integer(element, "seed") }, attributes: ["amount", "min-size", "max-size", "color", "warmth", "drift", "seed"] };
+    case "TVStatic": return { value: { kind: "tv-static", amount: numeric(element, "amount"), noiseSizePx: numeric(element, "size"), scanLineOpacity: numeric(element, "scan-lines"), motionRatePxPerFrame: numeric(element, "motion-rate"), seed: integer(element, "seed") }, attributes: ["amount", "size", "scan-lines", "motion-rate", "seed"] };
+    default: throw new Error(`${element.name} is not an official self-contained Screen Overlay component.`);
+  }
+}
+
+export const decodeScreenOverlaySurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  allowed(element, ["id", "canvas", "semantic"]); const id = text(element, "id");
+  const canvas = ref(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference);
+  const context = resolveTemporalContext({ element, resolveReference });
+  const time = createTemporalSpace({ id: id, element, ...context });
+  const headerId = `${id}.header`; const records: SurfaceRecordDraft[] = [{ id: headerId, type: screenOverlayTypes.header,
+    value: { kind: "inline", value: sealScreenOverlayHeader({ id }) }, range: element.range }];
+  const temporalComponents: SurfaceComponentDraft[] = [...time.components];
+  const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [...time.fragments];
+  const fragmentItems: Parameters<typeof createScreenOverlayFragment>[0][number][] = [];
+  const inputs: Record<string, typeof canvas.ref> = { canvas: canvas.ref, header: { kind: "record", id: headerId }, space: time.space.ref };
+  let index = 0;
+  for (const child of element.children) {
+    if (child.kind === "text") { if (child.value.trim()) throw new Error(`${element.name} accepts only component children.`); continue; }
+    if (child.children.some((node) => node.kind === "element" || node.value.trim())) throw new Error(`${child.name} must be empty.`);
+    index += 1; const suffix = String(index).padStart(4, "0"); const decoded = content(child);
+    allowed(child, ["id", "z", ...TIMING, ...decoded.attributes]);
+    const itemSpec = sealScreenOverlayItemSpec({
+      id: optionalText(child, "id") ?? `${id}.${decoded.value.kind}.${suffix}`, content: decoded.value,
+      stackingOrder: integer(child, "z") });
+    const temporal = createTemporalWindowProjection({ id: itemSpec.id, element: child, ...context, space: time.space, resolveReference });
+    records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);
+    const specId = `${id}.item.${suffix}.spec`; const specName = `item-${suffix}-spec`;
+    records.push({ id: specId, type: screenOverlayTypes.itemSpec, value: { kind: "inline", value: itemSpec }, range: child.range });
+    const windowName = `item-${suffix}-window`;
+    inputs[specName] = { kind: "record", id: specId }; inputs[windowName] = temporal.ref;
+    fragmentItems.push({ specName, windowName });
+  }
+  if (fragmentItems.length === 0) throw new Error(`${element.name} requires at least one component.`);
+  const fragment = createScreenOverlayFragment(fragmentItems);
+  return { records, components: [...temporalComponents, { id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range }], fragments: [...temporalFragments, fragment], exports: [`${id}.program`, `${id}.track`] };
+};

package/packages/screen-overlay/src/types.ts

@@ -0,0 +1,69 @@
+import type { FrameSpan } from "@hypit/composition";
+
+export type FlashOverlay = {
+  readonly kind: "flash"; readonly color: string; readonly intensity: number;
+  readonly attackFrames: number; readonly holdFrames: number; readonly decayFrames: number;
+};
+export type ColorWashOverlay = { readonly kind: "color-wash"; readonly color: string; readonly opacity: number };
+export type VignetteOverlay = {
+  readonly kind: "vignette"; readonly center: { readonly x: number; readonly y: number };
+  readonly radius: { readonly x: number; readonly y: number }; readonly softness: number;
+  readonly color: string; readonly opacity: number;
+};
+export type ScanLinesOverlay = {
+  readonly kind: "scan-lines"; readonly spacingPx: number; readonly thicknessPx: number;
+  readonly angleDeg: number; readonly opacity: number; readonly travelPx: number;
+};
+export type DirectionalMatteOverlay = {
+  readonly kind: "directional-matte"; readonly angleDeg: number; readonly coverage: number;
+  readonly feather: number; readonly color: string; readonly opacity: number;
+  readonly progress: { readonly from: number; readonly to: number };
+};
+export type WhipVeilOverlay = {
+  readonly kind: "whip-veil"; readonly direction: "left" | "right" | "up" | "down";
+  readonly widthPx: number; readonly softnessPx: number; readonly travelPx: number; readonly opacity: number;
+};
+export type GlitchVeilOverlay = {
+  readonly kind: "glitch-veil"; readonly bars: number; readonly colors: readonly string[];
+  readonly opacity: number; readonly travelPx: number; readonly seed: number;
+};
+export type GrainOverlay = {
+  readonly kind: "grain"; readonly amount: number; readonly grainSizePx: number;
+  readonly chroma: "monochrome" | "color"; readonly motionRatePxPerFrame: number; readonly seed: number;
+};
+export type LightLeakOverlay = {
+  readonly kind: "light-leak"; readonly colors: readonly string[]; readonly angleDeg: number;
+  readonly softness: number; readonly travelPx: number; readonly intensity: number; readonly seed: number;
+};
+export type BokehOverlay = {
+  readonly kind: "bokeh"; readonly amount: number; readonly sizeMinPx: number; readonly sizeMaxPx: number;
+  readonly color: string; readonly warmth: number; readonly driftPx: number; readonly seed: number;
+};
+export type TvStaticOverlay = {
+  readonly kind: "tv-static"; readonly amount: number; readonly noiseSizePx: number;
+  readonly scanLineOpacity: number; readonly motionRatePxPerFrame: number; readonly seed: number;
+};
+
+export type ScreenOverlayComponent =
+  | FlashOverlay | ColorWashOverlay | VignetteOverlay | ScanLinesOverlay | DirectionalMatteOverlay
+  | WhipVeilOverlay | GlitchVeilOverlay | GrainOverlay | LightLeakOverlay | BokehOverlay | TvStaticOverlay;
+
+export type ScreenOverlayItemSpec = {
+  readonly id: string;
+  readonly content: ScreenOverlayComponent;
+  readonly stackingOrder: number;
+};
+export type ScreenOverlayHeader = { readonly id: string };
+export type ScreenOverlayItemProgram = {
+  readonly id: string;
+  /** Author-owned Item realized by this externally projected window. */
+  readonly subjectId: string;
+  readonly span: FrameSpan;
+  readonly content: ScreenOverlayComponent;
+  readonly stacking: { readonly order: number; readonly tieBreak: string };
+};
+export type ScreenOverlaySet = { readonly items: readonly ScreenOverlayItemProgram[] };
+export type ScreenOverlayProgram = {
+  readonly id: string;
+  readonly items: readonly ScreenOverlayItemProgram[];
+};

package/packages/screen-overlay-studio/README.md

@@ -0,0 +1,3 @@
+# `@hypit/screen-overlay-studio`
+
+Hypit Studio Companion for `@hypit/screen-overlay`.

package/packages/screen-overlay-studio/package.json

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

package/packages/screen-overlay-studio/src/activation.ts

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

package/packages/screen-overlay-studio/src/index.ts

@@ -0,0 +1,80 @@
+import { screenOverlayModuleRef, screenOverlayTypes } from "@hypit/screen-overlay";
+import type { ScreenOverlayProgram } from "@hypit/screen-overlay";
+import { compositionTypes } from "@hypit/composition";
+import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration } from "@hypit/studio-adapter";
+import { childEntities, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
+
+function projectOverlays(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+  const program = requiredSurfaceValue(context, "program") as ScreenOverlayProgram;
+  const items = program.items.map((item) => ({
+    id: item.id,
+    subjectId: item.subjectId,
+    startFrame: item.span.startFrame,
+    endFrameExclusive: item.span.endFrameExclusive,
+    stackOrder: item.stacking.order,
+    sourceTypes: [screenOverlayTypes.itemSpec],
+  }));
+  return childEntities(context, items, "screen-overlay", "standard").map((entity, index) => {
+    const item = program.items[index];
+    if (item === undefined) return entity;
+    const temporal = temporalLineageFor(context, item.id, "window");
+    const semanticSource = temporalSemanticSource(temporal);
+    return {
+      ...entity,
+      display: { title: item.content.kind.replaceAll("-", " "), layers: [] },
+      ...(semanticSource?.id === undefined
+        ? {}
+        : { markerId: semanticSource.id }),
+      ...(temporal === undefined ? {} : { temporal }),
+    };
+  });
+}
+
+const overlayOptions: Readonly<Record<string, readonly string[]>> = {
+  direction: ["left", "right", "up", "down"],
+  chroma: ["monochrome", "color"],
+};
+
+const overlayNames = [
+  "color", "intensity", "opacity", "attack", "hold", "decay", "center-x", "center-y", "radius-x", "radius-y",
+  "softness", "spacing", "thickness", "angle", "travel", "coverage", "feather", "from", "to", "direction",
+  "width", "bars", "colors", "seed", "amount", "size", "chroma", "motion-rate", "min-size", "max-size",
+  "warmth", "drift", "scan-lines", "z",
+] as const;
+
+function title(name: string): string {
+  return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+
+const overlayGeometry = new Set(["center-x", "center-y", "radius-x", "radius-y", "width", "size", "min-size", "max-size", "z"]);
+const overlayMotion = new Set(["attack", "hold", "decay", "travel", "from", "to", "motion-rate", "drift"]);
+const overlayColor = new Set(["color", "colors"]);
+
+const overlayInspector: readonly StudioInspectorFieldDeclaration[] = overlayNames.map((binding) => {
+  const domain = overlayGeometry.has(binding) ? "where" as const : overlayMotion.has(binding) ? "when" as const : "how" as const;
+  const page = overlayGeometry.has(binding) ? "Geometry" : overlayMotion.has(binding) ? "Motion" : overlayColor.has(binding) ? "Color" : "Effect";
+  const options = overlayOptions[binding];
+  const control = options !== undefined ? "select" as const
+    : binding === "color" ? "color" : binding === "colors" ? "text" : "number";
+  return {
+    binding, label: title(binding), domain,
+    page: { id: page.toLowerCase(), label: page }, section: { id: page.toLowerCase(), label: page },
+    control,
+    ...(options === undefined ? {} : { options }),
+  };
+});
+
+export const screenOverlayStudioTrackCompanions: readonly StudioTrackCompanion[] = [
+  {
+    id: "track", role: "track",
+    output: { type: compositionTypes.visualTrack, surface: "track", modules: [screenOverlayModuleRef] },
+    family: "screen-overlay", tone: "orange", icon: "component",
+    bindings: [
+      ...overlayNames.map((name) => ({ name, writable: true })),
+    ],
+    inspector: overlayInspector,
+    requiredValues: ["program"], project: projectOverlays,
+    poster: { source: "surface-preview" },
+    lane: { heightPx: 52 },
+  },
+];

package/packages/script/README.md

@@ -0,0 +1,137 @@
+# `@hypit/script`
+
+Official raw Script Surface for the Markup Frontend. It parses prose-first named Segment blocks,
+newline-independent Role Cues, Dual Text, Selection and Moment syntax, and lowers them to a
+canonical authored Narrative value with exactly `2M + 2N + 2` semantic anchor identities: both
+ends of every Token and Segment, plus the Script Program's own start and end.
+
+The package is an ordinary statically declared Surface module. Core does not import it and does not
+know that Script, Segment or Narrative exist.
+
+```svml
+<script id="story">
+  @answer
+
+  <opening>
+    <ALICE> I will make the first point.
+    <BOB> Then I will answer.
+  </opening>
+
+  <pause/>
+  @/answer
+</script>
+```
+
+`<opening>` opens a Segment named `opening`; `</opening>` closes that exact Segment. While the
+parser is inside a Segment, a valid bare tag such as `<ALICE>` is a Role Cue. This is parser state,
+not indentation: the compact spelling
+`<opening><ALICE>I speak first.<BOB>I answer.</opening>` has the same semantic value.
+
+A Role Cue is optional. Text before the first Role Cue is a roleless Turn, and Role state is reset
+when every Segment closes; a Role can never leak into the following Segment.
+
+An empty Segment such as `<empty></empty>` (or `<empty/>`) is valid. `empty` is an ordinary
+author-chosen name, not a reserved keyword. It retains the Segment identity and both boundary anchors
+while contributing no Tokens or spoken text. This supports wordless passages in the same semantic
+model: the associated normalized media, not the empty tag, determines the SemanticTake's duration.
+
+The package exports its Manifest, `parseScript`, semantic/source-map projection helpers, a
+semantic-preserving formatter and the raw `decodeScriptSurface` handler. Source ranges and parser
+state remain private to Script; its authored Narrative Record uses the Frontend-neutral type from
+`@hypit/narrative`, so third-party author surfaces can feed the same WhisperX, locator and caption
+components without importing Script internals.
+
+The Surface exports one full Narrative plus narrow, immutable views:
+
+- `script.segment.<id>` is a narrow `NarrativeExcerpt` used to associate a generated Take with one Segment;
+- `script.segment.<id>.dialogue` is ordinary `Text`: display-independent dialogue, including optional
+  Role cues and right-side Dual Text pronunciation, for a speech-video model;
+- `script.segment.<id>.speech` is ordinary pronunciation-only `Text` for duration estimation or TTS;
+- `script.caption` is one complete `CaptionDocument`: ordered display Words, N:M Alignment Units,
+  and authored Cue Breaks, empty when the Script has no visible Caption words;
+- `script.selection.<id>` is a reusable explicit Selection;
+- `script.moment.<id>` is a reusable explicit Moment.
+
+`@hypit/caption` projects `script.selection.<id>` or a Role onto complete Caption Alignment Units;
+it then joins those units to a SemanticTrack for frame timing. Seedance consumes dialogue `Text`,
+Estimate and TTS consume speech `Text`, and Speech Track consumes the Segment excerpt. None imports
+Script's parser AST. Another authoring package may produce the same ordinary Text, Narrative and
+CaptionDocument contracts.
+
+### Script vocabulary
+
+- **Segment**: a named structural passage, written `<opening>...</opening>`.
+- **Role Cue**: a speaker turn, written as a bare tag such as `<ALICE>` inside a Segment. The next
+  Role Cue or the Segment close ends that turn.
+- **Dual Text**: one authored speech span with separate display and spoken projections, written
+  `<display text | spoken text>`.
+- **Selection marker**: a named semantic range, written `@name ... @/name`.
+- **Moment marker**: a named semantic point, written `@name!`.
+- **CaptionDocument**: the Script-owned caption truth; it contains **Display Words**,
+  **Alignment Units** and **Cue Breaks**. It contains no seconds or frames.
+- **Token attribute**: a flat postfix display-word annotation such as `really{emphasis}` or
+  `really{emphasis,importance=2,tone=warm}`. Values may be strings, finite numbers or booleans. It
+  becomes `CaptionDisplayWord.attributes`; it is not a Selection and does not carry timing.
+
+Within Dual Text, an unescaped `@` is legal only on the spoken side. The display side is literal; write
+`\@` if an at-sign must be shown. An empty display side, such as `< | spoken words>`, keeps the speech
+tokens and omits them from Caption. `||` is an authored Caption Cue Break and must occur between
+complete Alignment Units.
+
+## Segments, turns and Cues are different boundaries
+
+A Segment names a structural production passage. It can contain several Role turns and be performed
+by one Take with several edited shots. A Role Cue changes who speaks; it neither creates a character
+asset nor requires another generated Take. `||` changes Caption grouping between complete Alignment
+Units; it does not split the Segment, cut the picture or end a Selection.
+
+```svml
+<script id="story">
+  <exchange>
+    <HOST> I use it || every day, || since <2012 | twenty twelve>.
+    <GUEST> Even @proof on holiday @/proof?
+    <HOST> @answer! Especially then.
+  </exchange>
+</script>
+```
+
+Dual Text preserves display spelling while supplying an explicit pronunciation. Its N:M Alignment
+Unit is indivisible for Caption timing and authored Cue Breaks. Roles are lexical speaking cues;
+the Source's model references and action direction bind them to the intended performers.
+
+English words and numbers normally form lexical units; Han characters form individual units, as do
+Hiragana and Katakana characters. A Latin name adjacent to Han text remains separate from the
+following characters. Display punctuation attaches to neighboring words without adding timing units.
+These units support precise timing and highlighting. A Caption Cue can hold a whole phrase of them;
+`||` chooses its handoff independently of character counts or visual line wrapping.
+
+## Selection and Moment affinity
+
+A marker selects the adjacent semantic anchor; it does not write a timecode. Inside a spoken
+passage, its affinity normally chooses a neighboring word boundary:
+
+| Marker | Boundary |
+| --- | --- |
+| `@name` | Selection opens at the next word's start: right affinity. |
+| `~@name` | Selection opens at the previous word's end: left affinity. |
+| `@/name` | Selection closes at the previous word's end: left affinity. |
+| `@/name~` | Selection closes at the next word's start: right affinity. |
+| `@name!` | Moment at the next word's start: right affinity. |
+| `~@name!` | Moment at the previous word's end: left affinity. |
+
+At structural edges, the parser retains the corresponding Segment or program boundary rather than
+inventing a neighboring word. Selection and Moment ids share one namespace. Selections can overlap,
+cross and span Segments; unlike tags, they do not need to nest.
+
+To join two visual Selections without exposing their inter-word pause, match affinity on both sides:
+
+```text
+@coffee my coffee @/coffee ~@smoothie my smoothie @/smoothie
+@coffee my coffee @/coffee~ @smoothie my smoothie @/smoothie
+```
+
+These are alternative spellings, not two occurrences to put in the same Script. In the first,
+“coffee” ends both the first Window and the gap's left boundary, so the smoothie Selection owns the
+pause. In the second, the next “my” starts both touching boundaries, so the coffee Selection owns it.
+Plain `@/coffee @smoothie` leaves the gap between previous word end and next word start outside both.
+The media consumer still decides playback and visual coverage inside those projected Windows.

package/packages/script/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@hypit/script",
+  "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/narrative": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/text": "workspace:*",
+    "@hypit/markup": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/core": "workspace:*"
+  }
+}

package/packages/script/src/activation.ts

@@ -0,0 +1,20 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+  decodeScriptSurface,
+  scriptManifest,
+  scriptModuleRef,
+  scriptMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: scriptManifest }],
+  hostFacets: [createMarkupSurfaceHostFacet({
+    module: scriptModuleRef,
+    declaration: scriptMarkupSurfaces.find((item) => item.name === "script")!,
+    handler: decodeScriptSurface,
+  })],
+};
+
+export default hypitPackage;

package/packages/script/src/edit.ts

@@ -0,0 +1,174 @@
+import type { SourceRange } from "@hypit/protocol";
+
+import { narrativeValue } from "./narrative.js";
+import { parseScript } from "./parser.js";
+import type { Affinity, ParsedNarrative, SemanticAnchor } from "./types.js";
+
+export type ScriptAnchorEditSite = {
+  readonly anchorId: string;
+  readonly kind: SemanticAnchor["kind"];
+  readonly segmentId?: string;
+  readonly offset: number;
+  readonly affinity: Affinity;
+  readonly placement: "before" | "after";
+};
+
+export type ScriptSelectionAdjustment = {
+  readonly id: string;
+  readonly startAnchorId: string;
+  readonly endAnchorId: string;
+};
+
+export type ScriptMomentAdjustment = {
+  readonly id: string;
+  readonly anchorId: string;
+};
+
+type Edit = { readonly range: SourceRange; readonly replacement: string };
+
+/** Script owns the exact source inverse of every one of its 2M + 2N + 2 anchors. */
+export function scriptAnchorEditSites(parsed: ParsedNarrative): readonly ScriptAnchorEditSite[] {
+  const segments = new Map(parsed.segments.map((segment) => [segment.id, segment] as const));
+  const tokens = new Map(parsed.tokens.map((token) => [token.id, token] as const));
+  return parsed.semanticIndex.anchors.map((anchor): ScriptAnchorEditSite => {
+    if (anchor.kind === "program-start") {
+      return {
+        anchorId: anchor.id, kind: anchor.kind, offset: parsed.sourceRange.start,
+        affinity: "left", placement: "before",
+      };
+    }
+    if (anchor.kind === "program-end") {
+      return {
+        anchorId: anchor.id, kind: anchor.kind, offset: parsed.sourceRange.end,
+        affinity: "right", placement: "after",
+      };
+    }
+    const segmentId = anchor.segmentId;
+    const segment = segments.get(segmentId);
+    if (segment === undefined) throw new Error(`Semantic Anchor ${anchor.id} names unknown Segment ${segmentId}.`);
+    if (anchor.kind === "segment-start") {
+      const first = parsed.tokens[segment.tokenStart];
+      return {
+        anchorId: anchor.id, kind: anchor.kind, segmentId,
+        offset: first?.range.start ?? segment.contentRange.start,
+        affinity: "left", placement: "before",
+      };
+    }
+    if (anchor.kind === "segment-end") {
+      const last = parsed.tokens[segment.tokenEndExclusive - 1];
+      return {
+        anchorId: anchor.id, kind: anchor.kind, segmentId,
+        offset: last?.range.end ?? segment.contentRange.end,
+        affinity: "right", placement: "after",
+      };
+    }
+    const token = anchor.tokenId === undefined ? undefined : tokens.get(anchor.tokenId);
+    if (token === undefined) throw new Error(`Semantic Anchor ${anchor.id} names no Script Token.`);
+    return anchor.kind === "token-start" ? {
+      anchorId: anchor.id, kind: anchor.kind, segmentId,
+      offset: token.range.start, affinity: "right", placement: "before",
+    } : {
+      anchorId: anchor.id, kind: anchor.kind, segmentId,
+      offset: token.range.end, affinity: "left", placement: "after",
+    };
+  });
+}
+
+function marker(id: string, edge: "open" | "close", affinity: Affinity): string {
+  if (edge === "open") return affinity === "left" ? `~@${id}` : `@${id}`;
+  return affinity === "left" ? `@/${id}` : `@/${id}~`;
+}
+
+function insertion(id: string, edge: "open" | "close", site: ScriptAnchorEditSite): string {
+  const value = marker(id, edge, site.affinity);
+  return site.placement === "before" ? `${value} ` : ` ${value}`;
+}
+
+function momentInsertion(id: string, site: ScriptAnchorEditSite): string {
+  const value = site.affinity === "left" ? `~@${id}!` : `@${id}!`;
+  return site.placement === "before" ? `${value} ` : ` ${value}`;
+}
+
+function applyEdits(source: string, edits: readonly Edit[]): string {
+  let next = source;
+  const ordered = [...edits].sort((left, right) =>
+    right.range.start - left.range.start || right.range.end - left.range.end);
+  for (const edit of ordered) {
+    if (edit.range.start < 0 || edit.range.end < edit.range.start || edit.range.end > source.length) {
+      throw new Error("Script marker edit lies outside its Source.");
+    }
+    next = `${next.slice(0, edit.range.start)}${edit.replacement}${next.slice(edit.range.end)}`;
+  }
+  return next;
+}
+
+/**
+ * Relocate one shared Selection by anchor identity. The returned Source is accepted only when
+ * reparsing proves the requested public Narrative, so Studio never edits prose by frame guess.
+ */
+export function adjustScriptSelection(input: {
+  readonly sourceName: string;
+  readonly source: string;
+  readonly parsed: ParsedNarrative;
+  readonly adjustment: ScriptSelectionAdjustment;
+}): string {
+  const selection = input.parsed.selections.find((candidate) => candidate.id === input.adjustment.id);
+  if (selection === undefined) throw new Error(`Script Selection ${input.adjustment.id} does not exist.`);
+  const sites = new Map(scriptAnchorEditSites(input.parsed).map((site) => [site.anchorId, site] as const));
+  const start = sites.get(input.adjustment.startAnchorId);
+  const end = sites.get(input.adjustment.endAnchorId);
+  if (start === undefined) throw new Error(`Selection start Anchor ${input.adjustment.startAnchorId} does not exist.`);
+  if (end === undefined) throw new Error(`Selection end Anchor ${input.adjustment.endAnchorId} does not exist.`);
+
+  const edits: Edit[] = [];
+  if (selection.startAnchorId !== start.anchorId) {
+    edits.push({ range: selection.open.range, replacement: "" });
+    edits.push({ range: { start: start.offset, end: start.offset }, replacement: insertion(selection.id, "open", start) });
+  }
+  if (selection.endAnchorId !== end.anchorId) {
+    edits.push({ range: selection.close.range, replacement: "" });
+    edits.push({ range: { start: end.offset, end: end.offset }, replacement: insertion(selection.id, "close", end) });
+  }
+  if (edits.length === 0) return input.source;
+  const next = applyEdits(input.source, edits);
+  const reparsed = parseScript(input.sourceName, next);
+  const rewritten = reparsed.selections.find((candidate) => candidate.id === selection.id);
+  if (rewritten?.startAnchorId !== start.anchorId || rewritten.endAnchorId !== end.anchorId) {
+    throw new Error(`Script refused to move Selection ${selection.id} to the requested Anchors.`);
+  }
+  const before = narrativeValue(input.parsed, "comparison") as unknown as { readonly selections: readonly { readonly id: string }[] };
+  const after = narrativeValue(reparsed, "comparison") as unknown as { readonly selections: readonly { readonly id: string }[] };
+  if (before.selections.length !== after.selections.length
+    || before.selections.some((item) => !after.selections.some((candidate) => candidate.id === item.id))) {
+    throw new Error("Script Selection adjustment changed authored identities.");
+  }
+  return next;
+}
+
+/** Relocate one Moment to an exact semantic Anchor without changing its identity. */
+export function adjustScriptMoment(input: {
+  readonly sourceName: string;
+  readonly source: string;
+  readonly parsed: ParsedNarrative;
+  readonly adjustment: ScriptMomentAdjustment;
+}): string {
+  const moment = input.parsed.moments.find((candidate) => candidate.id === input.adjustment.id);
+  if (moment === undefined) throw new Error(`Script Moment ${input.adjustment.id} does not exist.`);
+  const site = scriptAnchorEditSites(input.parsed).find((candidate) => candidate.anchorId === input.adjustment.anchorId);
+  if (site === undefined) throw new Error(`Moment Anchor ${input.adjustment.anchorId} does not exist.`);
+  if (moment.anchorId === site.anchorId) return input.source;
+  const next = applyEdits(input.source, [
+    { range: moment.range, replacement: "" },
+    { range: { start: site.offset, end: site.offset }, replacement: momentInsertion(moment.id, site) },
+  ]);
+  const reparsed = parseScript(input.sourceName, next);
+  const rewritten = reparsed.moments.find((candidate) => candidate.id === moment.id);
+  if (rewritten?.anchorId !== site.anchorId) {
+    throw new Error(`Script refused to move Moment ${moment.id} to the requested Anchor.`);
+  }
+  if (reparsed.moments.length !== input.parsed.moments.length
+    || input.parsed.moments.some((item) => !reparsed.moments.some((candidate) => candidate.id === item.id))) {
+    throw new Error("Script Moment adjustment changed authored identities.");
+  }
+  return next;
+}

package/packages/script/src/error.ts

@@ -0,0 +1,13 @@
+export class ScriptSyntaxError extends Error {
+  readonly code: string;
+  readonly sourceName: string;
+  readonly offset: number | undefined;
+
+  constructor(code: string, message: string, sourceName: string, offset?: number) {
+    super(`${code}: ${message}${offset === undefined ? "" : ` (${sourceName}:${offset})`}`);
+    this.name = "ScriptSyntaxError";
+    this.code = code;
+    this.sourceName = sourceName;
+    this.offset = offset;
+  }
+}