Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

feat(semantic-take-adjust): add explicit anchor corrections

kashorincfd6ae91477a
diff --git a/packages/semantic-take-adjust/package.json b/packages/semantic-take-adjust/package.json
new file mode 100644
index 00000000..e88cb884
--- /dev/null
+++ b/packages/semantic-take-adjust/package.json
@@ -0,0 +1,21 @@
+{
+ "name": "@hypit/semantic-take-adjust",
+ "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/component-kit": "workspace:*",
+ "@hypit/elaborator": "workspace:*",
+ "@hypit/markup": "workspace:*",
+ "@hypit/narrative": "workspace:*",
+ "@hypit/protocol": "workspace:*",
+ "@hypit/speech": "workspace:*"
+ }
+}
diff --git a/packages/semantic-take-adjust/src/activation.ts b/packages/semantic-take-adjust/src/activation.ts
new file mode 100644
index 00000000..add3fc5d
--- /dev/null
+++ b/packages/semantic-take-adjust/src/activation.ts
@@ -0,0 +1,22 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+ decodeSemanticTakeAdjustSurface,
+ semanticTakeAdjustComponent,
+ semanticTakeAdjustManifest,
+ semanticTakeAdjustMarkupSurfaces,
+ semanticTakeAdjustModuleRef,
+} from "./index.js";
+
+export const hypitPackage = {
+ format: "hypit.node-package@1" as const,
+ modules: [{ manifest: semanticTakeAdjustManifest }],
+ components: [semanticTakeAdjustComponent],
+ hostFacets: [createMarkupSurfaceHostFacet({
+ module: semanticTakeAdjustModuleRef,
+ declaration: semanticTakeAdjustMarkupSurfaces.find((item) => item.name === "semantic-take")!,
+ handler: decodeSemanticTakeAdjustSurface,
+ })],
+};
+
+export default hypitPackage;
diff --git a/packages/semantic-take-adjust/src/component.ts b/packages/semantic-take-adjust/src/component.ts
new file mode 100644
index 00000000..d175b143
--- /dev/null
+++ b/packages/semantic-take-adjust/src/component.ts
@@ -0,0 +1,31 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import { canonicalize } from "@hypit/protocol";
+import type { StoredValue } from "@hypit/protocol";
+import type { SemanticTake } from "@hypit/speech";
+
+import { semanticTakeAdjustProducers } from "./manifest.js";
+import { adjustSemanticTake } from "./program.js";
+import type { SemanticTakeAdjustmentPlan } from "./types.js";
+
+function inline<T>(value: StoredValue | undefined, subject: string): T {
+ if (value?.kind !== "inline") throw new Error(`${subject} must be inline.`);
+ return value.value as unknown as T;
+}
+
+export const semanticTakeAdjustComponent = {
+ producers: [{
+ producer: semanticTakeAdjustProducers.adjust,
+ handler: ({ inputs }) => ({
+ outputs: {
+ take: {
+ kind: "inline",
+ value: canonicalize(adjustSemanticTake(
+ inline<SemanticTake>(inputs.source?.value, "SemanticTake"),
+ inline<SemanticTakeAdjustmentPlan>(inputs.plan?.value, "SemanticTake adjustment plan"),
+ )),
+ },
+ },
+ needs: {},
+ }),
+ }],
+} satisfies ComponentPackage;
diff --git a/packages/semantic-take-adjust/src/fragment.ts b/packages/semantic-take-adjust/src/fragment.ts
new file mode 100644
index 00000000..87aa1795
--- /dev/null
+++ b/packages/semantic-take-adjust/src/fragment.ts
@@ -0,0 +1,24 @@
+import { sealGraphFragment } from "@hypit/elaborator";
+import { speechTypes } from "@hypit/speech";
+
+import { semanticTakeAdjustProducers, semanticTakeAdjustTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+
+export const semanticTakeAdjustFragment = sealGraphFragment({
+ inputs: [
+ { name: "source", type: speechTypes.semanticTake },
+ { name: "plan", type: semanticTakeAdjustTypes.plan },
+ ],
+ operations: [{
+ id: "adjust",
+ producer: semanticTakeAdjustProducers.adjust,
+ inputs: { source: input("source"), plan: input("plan") },
+ result: { kind: "output", name: "take" },
+ }],
+ exports: [{
+ name: "take",
+ type: speechTypes.semanticTake,
+ root: { kind: "fragment-operation", operation: "adjust" },
+ }],
+});
diff --git a/packages/semantic-take-adjust/src/index.ts b/packages/semantic-take-adjust/src/index.ts
new file mode 100644
index 00000000..0212647a
--- /dev/null
+++ b/packages/semantic-take-adjust/src/index.ts
@@ -0,0 +1,12 @@
+export { semanticTakeAdjustComponent } from "./component.js";
+export { semanticTakeAdjustFragment } from "./fragment.js";
+export {
+ semanticTakeAdjustManifest,
+ semanticTakeAdjustMarkupSurfaces,
+ semanticTakeAdjustModuleRef,
+ semanticTakeAdjustProducers,
+ semanticTakeAdjustTypes,
+} from "./manifest.js";
+export { adjustSemanticTake } from "./program.js";
+export { decodeSemanticTakeAdjustSurface } from "./surface.js";
+export type { SemanticTakeAdjustmentPlan, SemanticTakeAnchorAdjustment } from "./types.js";
diff --git a/packages/semantic-take-adjust/src/manifest.ts b/packages/semantic-take-adjust/src/manifest.ts
new file mode 100644
index 00000000..897811a7
--- /dev/null
+++ b/packages/semantic-take-adjust/src/manifest.ts
@@ -0,0 +1,57 @@
+import { narrativeDependency } from "@hypit/narrative";
+import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
+import { speechDependency, speechTypes } from "@hypit/speech";
+
+export const semanticTakeAdjustModuleRef = { name: "@hypit/semantic-take-adjust", version: "1" } as const;
+
+export const semanticTakeAdjustTypes = {
+ plan: { module: semanticTakeAdjustModuleRef, name: "SemanticTakeAdjustmentPlan" },
+} satisfies Record<string, TypeRef>;
+
+export const semanticTakeAdjustProducers = {
+ adjust: { module: semanticTakeAdjustModuleRef, name: "adjust-semantic-take" },
+} satisfies Record<string, ProducerRef>;
+
+export const semanticTakeAdjustMarkupSurfaces = [{
+ name: "semantic-take",
+ tag: "SemanticTake",
+ mode: "structured",
+ outputs: [semanticTakeAdjustTypes.plan, speechTypes.semanticTake],
+ vocabulary: {
+ summary: "Applies explicit author corrections to measured SemanticTake anchor frames without changing its media or Script identities.",
+ attributes: [
+ { name: "id", kind: "identifier", required: true,
+ summary: "Names the corrected SemanticTake." },
+ { name: "source", kind: "reference", required: true, accepts: [speechTypes.semanticTake],
+ summary: "Selects the measured SemanticTake being corrected." },
+ ],
+ ports: [{ name: "take", type: speechTypes.semanticTake,
+ summary: "The corrected SemanticTake, addressed as `<id>.take`." }],
+ example: `<adjust:SemanticTake id="opening-corrected" source={opening-measured.take}>
+ <adjust:Anchor at={story.moment.answer} frame="63"/>
+</adjust:SemanticTake>`,
+ notes: [
+ "Each Anchor names an author-declared Script Moment and gives its exact Segment-local frame.",
+ "This is an explicit correction layer over measured evidence; it does not guess timing or modify media.",
+ "Every Token boundary that owns the corrected Anchor is updated together, preserving SemanticTake identity invariants.",
+ ],
+ },
+}] as const;
+
+export const semanticTakeAdjustManifest: ModuleManifest = {
+ format: "hypit.module@1",
+ name: semanticTakeAdjustModuleRef.name,
+ version: semanticTakeAdjustModuleRef.version,
+ dependencies: [narrativeDependency, speechDependency],
+ types: [{ name: semanticTakeAdjustTypes.plan.name }],
+ capabilities: [],
+ producers: [{
+ name: semanticTakeAdjustProducers.adjust.name,
+ inputs: [
+ { name: "source", type: speechTypes.semanticTake },
+ { name: "plan", type: semanticTakeAdjustTypes.plan },
+ ],
+ outputs: [{ name: "take", type: speechTypes.semanticTake }],
+ needs: [],
+ }],
+};
diff --git a/packages/semantic-take-adjust/src/program.ts b/packages/semantic-take-adjust/src/program.ts
new file mode 100644
index 00000000..663ca951
--- /dev/null
+++ b/packages/semantic-take-adjust/src/program.ts
@@ -0,0 +1,49 @@
+import { assertSemanticTakeIdentity, sealSemanticTake } from "@hypit/speech";
+import type { SemanticTake } from "@hypit/speech";
+
+import type { SemanticTakeAdjustmentPlan } from "./types.js";
+
+export function adjustSemanticTake(
+ source: SemanticTake,
+ plan: SemanticTakeAdjustmentPlan,
+): SemanticTake {
+ assertSemanticTakeIdentity(source);
+ if (plan.narrativeId !== source.narrativeId) {
+ throw new Error(`SemanticTake adjustment belongs to Narrative ${plan.narrativeId}, not ${source.narrativeId}.`);
+ }
+ if (plan.anchors.length === 0) throw new Error("SemanticTake adjustment requires at least one Anchor.");
+
+ const sourceAnchorIds = new Set(source.anchors.map((anchor) => anchor.identity));
+ const adjusted = new Map<string, number>();
+ for (const anchor of plan.anchors) {
+ if (!sourceAnchorIds.has(anchor.anchorId)) {
+ throw new Error(`SemanticTake does not contain adjusted Anchor ${anchor.anchorId}.`);
+ }
+ if (adjusted.has(anchor.anchorId)) {
+ throw new Error(`SemanticTake Anchor ${anchor.anchorId} is adjusted more than once.`);
+ }
+ if (!Number.isSafeInteger(anchor.frame) || anchor.frame < 0 || anchor.frame > source.media.timeline.frameCount) {
+ throw new Error(`SemanticTake Anchor ${anchor.anchorId} has an invalid adjusted frame.`);
+ }
+ adjusted.set(anchor.anchorId, anchor.frame);
+ }
+
+ const frame = (anchorId: string, fallback: number): number => adjusted.get(anchorId) ?? fallback;
+ return sealSemanticTake({
+ ...source,
+ segment: {
+ ...source.segment,
+ startFrame: frame(source.segment.startAnchorId, source.segment.startFrame),
+ endFrameExclusive: frame(source.segment.endAnchorId, source.segment.endFrameExclusive),
+ },
+ anchors: source.anchors.map((anchor) => ({
+ ...anchor,
+ frame: frame(anchor.identity, anchor.frame),
+ })),
+ tokens: source.tokens.map((token) => ({
+ ...token,
+ startFrame: frame(token.startAnchorId, token.startFrame),
+ endFrameExclusive: frame(token.endAnchorId, token.endFrameExclusive),
+ })),
+ });
+}
diff --git a/packages/semantic-take-adjust/src/surface.ts b/packages/semantic-take-adjust/src/surface.ts
new file mode 100644
index 00000000..b2cbfa68
--- /dev/null
+++ b/packages/semantic-take-adjust/src/surface.ts
@@ -0,0 +1,96 @@
+import {
+ assertExactAttributes,
+ localName,
+ textAttribute,
+} from "@hypit/markup";
+import type {
+ MarkupAttributeValue,
+ StructuredElement,
+ StructuredSurfaceHandler,
+ SurfaceResolvedReference,
+} from "@hypit/markup";
+import { narrativeTypes } from "@hypit/narrative";
+import type { NarrativeMomentRef } from "@hypit/narrative";
+import { canonicalize, sameType } from "@hypit/protocol";
+import { speechTypes } from "@hypit/speech";
+
+import { semanticTakeAdjustFragment } from "./fragment.js";
+import { semanticTakeAdjustTypes } from "./manifest.js";
+import type { SemanticTakeAdjustmentPlan } from "./types.js";
+
+function reference(
+ element: StructuredElement,
+ name: string,
+ expected: SurfaceResolvedReference["type"],
+ resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ const raw: MarkupAttributeValue | undefined = element.attributes[name];
+ if (typeof raw !== "object" || raw.kind !== "reference") {
+ throw new Error(`${element.name}.${name} must be a whole-value reference.`);
+ }
+ const resolved = resolveReference(raw.path);
+ if (resolved === undefined) throw new Error(`${element.name}.${name} cannot resolve ${raw.path}.`);
+ if (!sameType(resolved.type, expected)) throw new Error(`${element.name}.${name} has the wrong type.`);
+ return resolved;
+}
+
+function inline<T>(value: SurfaceResolvedReference, subject: string): T {
+ if (value.record?.value.kind !== "inline") throw new Error(`${subject} must reference an authored inline Record.`);
+ return value.record.value.value as unknown as T;
+}
+
+function frameAttribute(element: StructuredElement): number {
+ const value = Number(textAttribute(element, "frame"));
+ if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${element.name}.frame must be a non-negative integer.`);
+ return value;
+}
+
+export const decodeSemanticTakeAdjustSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ assertExactAttributes(element, ["id", "source"]);
+ const id = textAttribute(element, "id");
+ const source = reference(element, "source", speechTypes.semanticTake, resolveReference);
+ const moments: NarrativeMomentRef[] = [];
+ const anchors: SemanticTakeAdjustmentPlan["anchors"][number][] = [];
+
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ if (child.value.trim()) throw new Error(`${element.name} accepts only Anchor children.`);
+ continue;
+ }
+ if (localName(child.name) !== "Anchor") throw new Error(`${element.name} accepts only Anchor children.`);
+ assertExactAttributes(child, ["at", "frame"]);
+ if (child.children.some((item) => item.kind === "element" || item.value.trim())) {
+ throw new Error(`${child.name} must be empty.`);
+ }
+ const moment = inline<NarrativeMomentRef>(
+ reference(child, "at", narrativeTypes.moment, resolveReference),
+ `${child.name}.at`,
+ );
+ moments.push(moment);
+ anchors.push({ anchorId: moment.anchorId, frame: frameAttribute(child) });
+ }
+ if (anchors.length === 0) throw new Error(`${element.name} requires at least one Anchor child.`);
+ const narrativeId = moments[0]!.narrativeId;
+ if (moments.some((moment) => moment.narrativeId !== narrativeId)) {
+ throw new Error(`${element.name} cannot mix Moments from different Narratives.`);
+ }
+
+ const planId = `${id}.plan`;
+ const plan: SemanticTakeAdjustmentPlan = { narrativeId, anchors };
+ return {
+ records: [{
+ id: planId,
+ type: semanticTakeAdjustTypes.plan,
+ value: { kind: "inline", value: canonicalize(plan) },
+ range: element.range,
+ }],
+ components: [{
+ id,
+ fragment: semanticTakeAdjustFragment.id,
+ inputs: { source: source.ref, plan: { kind: "record", id: planId } },
+ outputs: { take: `${id}.take` },
+ range: element.range,
+ }],
+ fragments: [semanticTakeAdjustFragment],
+ };
+};
diff --git a/packages/semantic-take-adjust/src/types.ts b/packages/semantic-take-adjust/src/types.ts
new file mode 100644
index 00000000..e74625f3
--- /dev/null
+++ b/packages/semantic-take-adjust/src/types.ts
@@ -0,0 +1,9 @@
+export type SemanticTakeAnchorAdjustment = {
+ readonly anchorId: string;
+ readonly frame: number;
+};
+
+export type SemanticTakeAdjustmentPlan = {
+ readonly narrativeId: string;
+ readonly anchors: readonly SemanticTakeAnchorAdjustment[];
+};
diff --git a/packages/semantic-take-adjust/test/semantic-take-adjust.test.ts b/packages/semantic-take-adjust/test/semantic-take-adjust.test.ts
new file mode 100644
index 00000000..6e7a27cc
--- /dev/null
+++ b/packages/semantic-take-adjust/test/semantic-take-adjust.test.ts
@@ -0,0 +1,51 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { adjustSemanticTake } from "../src/program.js";
+import type { SemanticTake } from "@hypit/speech";
+
+const source = {
+ narrativeId: "story",
+ media: {
+ timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 100 },
+ visual: {
+ artifact: { kind: "blob", digest: `sha256:${"0".repeat(64)}`, size: 1, mediaType: "video/mp4" },
+ width: 720,
+ height: 1280,
+ },
+ },
+ segment: {
+ segmentId: "opening",
+ startAnchorId: "opening:start",
+ endAnchorId: "opening:end",
+ startFrame: 0,
+ endFrameExclusive: 100,
+ },
+ tokens: [{
+ tokenId: "answer",
+ segmentId: "opening",
+ text: "Ajá",
+ startAnchorId: "answer:start",
+ endAnchorId: "answer:end",
+ startFrame: 58,
+ endFrameExclusive: 85,
+ }],
+ anchors: [
+ { identity: "opening:start", frame: 0 },
+ { identity: "answer:start", frame: 58 },
+ { identity: "answer:end", frame: 85 },
+ { identity: "opening:end", frame: 100 },
+ ],
+} satisfies SemanticTake;
+
+test("adjusts an authored semantic anchor without changing media", () => {
+ const adjusted = adjustSemanticTake(source, {
+ narrativeId: "story",
+ anchors: [{ anchorId: "answer:start", frame: 63 }],
+ });
+
+ assert.equal(adjusted.tokens[0]?.startFrame, 63);
+ assert.equal(adjusted.tokens[0]?.endFrameExclusive, 85);
+ assert.equal(adjusted.anchors.find((anchor) => anchor.identity === "answer:start")?.frame, 63);
+ assert.deepEqual(adjusted.media, source.media);
+});