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(studio): add author-directed time and parameter editing

kashorin54cf1f32eb5a
diff --git a/package.json b/package.json
index b77b27db..f1d13381 100644
--- a/package.json
+++ b/package.json
@@ -115,6 +115,8 @@
"packages/*/*.html",
"packages/*/package.json",
"packages/*/README.md",
+ "packages/temporal-markup/EDITING.md",
+ "packages/studio/INSPECTOR.md",
"services/image-opencv/pyproject.toml",
"services/image-opencv/package.json",
"services/image-opencv/uv.lock",
diff --git a/packages/audio-track-studio/src/index.ts b/packages/audio-track-studio/src/index.ts
index cb84751b..e1778f69 100644
--- a/packages/audio-track-studio/src/index.ts
+++ b/packages/audio-track-studio/src/index.ts
@@ -48,22 +48,25 @@ export const audioTrackStudioTrackCompanions: readonly StudioTrackCompanion[] =
],
inspector: [
{
- binding: "playback", label: "Playback", domain: "how",
+ binding: "playback", label: "Playback", domain: "when",
page: { id: "playback", label: "Playback" }, section: { id: "playback", label: "Playback" },
control: "select", options: ["once", "once-start", "once-end", "loop", "loop-start", "loop-end", "stretch"],
},
...(["trim-start", "trim-end"] as const).map((binding) => ({
- binding, label: binding === "trim-start" ? "Trim Start" : "Trim End", domain: "how" as const,
- page: { id: "playback", label: "Playback" }, section: { id: "trim", label: "Trim" }, control: "text" as const,
+ binding, label: binding === "trim-start" ? "Trim Start" : "Trim End", domain: "when" as const,
+ page: { id: "playback", label: "Playback" }, section: { id: "trim", label: "Trim" }, control: "number" as const,
+ number: { suffixes: ["ms", "s", "f"], minimum: 0 },
})),
...(["min-rate", "max-rate", "gain"] as const).map((binding) => ({
binding, label: binding === "min-rate" ? "Minimum Rate" : binding === "max-rate" ? "Maximum Rate" : "Gain",
domain: "how" as const, page: { id: "mix", label: "Mix" }, section: { id: "mix", label: "Mix" },
control: "number" as const,
+ unit: "%", number: { scale: 100, minimum: 0, step: 1 },
})),
...(["fade-in", "fade-out"] as const).map((binding) => ({
binding, label: binding === "fade-in" ? "Fade In" : "Fade Out", domain: "when" as const,
- page: { id: "fade", label: "Fade" }, section: { id: "fade", label: "Fade" }, control: "text" as const,
+ page: { id: "fade", label: "Fade" }, section: { id: "fade", label: "Fade" }, control: "number" as const,
+ number: { suffixes: ["ms", "s", "f"], minimum: 0 },
})),
],
requiredValues: ["program"], project: projectAudio,
diff --git a/packages/caption-fine-studio/package.json b/packages/caption-fine-studio/package.json
index 96a7fd5c..0a6eb21d 100644
--- a/packages/caption-fine-studio/package.json
+++ b/packages/caption-fine-studio/package.json
@@ -4,12 +4,17 @@
"license": "SEE LICENSE IN LICENSE",
"private": true,
"type": "module",
- "exports": { ".": "./src/index.ts" },
- "hypit": { "activation": "./src/activation.ts" },
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "hypit": {
+ "activation": "./src/activation.ts"
+ },
"dependencies": {
"@hypit/caption-fine": "workspace:*",
"@hypit/composition": "workspace:*",
"@hypit/narrative": "workspace:*",
- "@hypit/studio-adapter": "workspace:*"
+ "@hypit/studio-adapter": "workspace:*",
+ "@hypit/fonts-open": "workspace:*"
}
}
diff --git a/packages/caption-fine-studio/src/index.ts b/packages/caption-fine-studio/src/index.ts
index 09f40413..eb56c1b1 100644
--- a/packages/caption-fine-studio/src/index.ts
+++ b/packages/caption-fine-studio/src/index.ts
@@ -1,3 +1,4 @@
+import { openFontStudioFields } from "@hypit/fonts-open/studio";
import { captionFineMarkupSurfaces, captionFineModuleRef } from "@hypit/caption-fine";
import type { FineCaptionSchedule } from "@hypit/caption-fine";
import { compositionTypes } from "@hypit/composition";
@@ -12,6 +13,9 @@ import type {
import { requiredReferencedValue, requiredSurfaceValue, textLayer } from "@hypit/studio-adapter";
const styleSurface = captionFineMarkupSurfaces.find((surface) => surface.name === "style");
+
+const fontInspector = openFontStudioFields("program");
+
const recipeVocabulary = styleSurface?.vocabulary.attributes
.find((attribute) => attribute.name === "recipe")?.recipe ?? [];
@@ -83,6 +87,8 @@ const captionColorProperties = new Set([
"active-underline-color", "active-box-background", "active-box-border-color",
]);
const captionTextProperties = new Set(["loop"]);
+const captionPercentProperties = new Set(["x", "y", "width", "height", "opacity", "active-opacity", "active-scale"]);
+const captionPixelProperties = new Set(["size", "letter-spacing", "word-gap", "radius", "stroke-width", "border-width", "shadow-blur", "glow-blur"]);
export const captionFineInspectorFields: readonly StudioInspectorFieldDeclaration[] = recipeVocabulary.map((property) => {
const placement = captionPlacement.get(property.name);
@@ -96,6 +102,8 @@ export const captionFineInspectorFields: readonly StudioInspectorFieldDeclaratio
control: options !== undefined ? "select" : captionColorProperties.has(property.name) ? "color"
: captionTextProperties.has(property.name) ? "text" : "number",
...(options === undefined ? {} : { options }),
+ ...(captionPercentProperties.has(property.name) ? { unit: "%", number: { scale: 100, step: 1 } } : {}),
+ ...(captionPixelProperties.has(property.name) ? { unit: "px", number: { step: 1 } } : {}),
};
});
@@ -153,10 +161,11 @@ export const captionFineStudioTrackCompanions: readonly StudioTrackCompanion[] =
bindings: [
{
name: "program",
+ referenced: [fontInspector.binding],
recipe: { through: ["recipe"], bindings: recipeVocabulary.map(({ name }) => ({ name })) },
},
],
- inspector: captionFineInspectorFields,
+ inspector: [...fontInspector.fields, ...captionFineInspectorFields],
requiredValues: ["schedule"], project: projectCaption,
lane: { heightPx: 48 },
},
diff --git a/packages/comment-sticker-studio/src/index.ts b/packages/comment-sticker-studio/src/index.ts
index 85676973..7cfa8e5a 100644
--- a/packages/comment-sticker-studio/src/index.ts
+++ b/packages/comment-sticker-studio/src/index.ts
@@ -117,12 +117,13 @@ export const commentStickerStudioTrackCompanions: readonly StudioTrackCompanion[
inspector: [
...frameParameters.filter(({ writable }) => writable === true).map(({ name }) => ({
binding: `frame.${name}`, label: title(name), domain: "where" as const,
- page: { id: "frame", label: "Frame" }, section: { id: "frame", label: "Frame" }, control: "text" as const,
+ page: { id: "frame", label: "Frame" }, section: { id: "frame", label: "Frame" }, control: "number" as const, number: { suffixes: ["%", "px"], step: 1 },
})),
...commentInspector,
...["comment", "author", "header", "meta"].map((binding) => ({
binding, label: title(binding), domain: "how" as const,
page: { id: "copy", label: "Copy" }, section: { id: "copy", label: "Copy" }, control: "text" as const,
+ ...(binding === "comment" ? { multiline: true } : {}),
})),
],
requiredValues: ["program"], project: projectComments,
diff --git a/packages/fonts-open/README.md b/packages/fonts-open/README.md
index 1e1a0080..c7be6678 100644
--- a/packages/fonts-open/README.md
+++ b/packages/fonts-open/README.md
@@ -1,5 +1,10 @@
# `@hypit/fonts-open`
+The optional `@hypit/fonts-open/studio` export supplies data-only catalog choices for Companions.
+`openFontStudioFields(owner)` returns the explicit nested font binding and Inspector fields for a
+Style reference such as `program` or `style`. It edits the referenced catalog face's family, keeping
+its authored weight, style and fallback faces. Ordinary font validation still applies.
+
Workspace package exposing 109 redistributable open font families as exact,
Resource-backed `FontArtifactRef` values. The installed packages carry their font bytes and license
files. Author compilation and rendering never download fonts or inspect system font directories.
diff --git a/packages/fonts-open/package.json b/packages/fonts-open/package.json
index cc9ab456..d5943d2d 100644
--- a/packages/fonts-open/package.json
+++ b/packages/fonts-open/package.json
@@ -5,7 +5,8 @@
"private": true,
"type": "module",
"exports": {
- ".": "./src/index.ts"
+ ".": "./src/index.ts",
+ "./studio": "./src/studio.ts"
},
"hypit": {
"activation": "./src/activation.ts"
@@ -126,5 +127,8 @@
"@hypit/package-loader-node": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/markup": "workspace:*"
+ },
+ "devDependencies": {
+ "@hypit/studio-adapter": "workspace:*"
}
}
diff --git a/packages/fonts-open/src/studio.ts b/packages/fonts-open/src/studio.ts
new file mode 100644
index 00000000..d77c7722
--- /dev/null
+++ b/packages/fonts-open/src/studio.ts
@@ -0,0 +1,21 @@
+import type { StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-adapter";
+import { openFontFamilies } from "./catalog.js";
+
+/** Optional Companion declarations for the primary catalog face reached through a Style's font. */
+export function openFontStudioFields(owner: string): {
+ readonly binding: StudioSourceBindingDeclaration;
+ readonly fields: readonly StudioInspectorFieldDeclaration[];
+} {
+ return {
+ binding: { name: "font", referenced: [{ name: "family", writable: true }] },
+ fields: [{
+ binding: `${owner}.font.family`, label: "Font Family", domain: "how",
+ page: { id: "font", label: "Font" }, section: { id: "face", label: "Primary Face" },
+ summary: "Changes the shared catalog face. Its authored weight and style must be available in the selected family.",
+ control: "select",
+ options: Object.entries(openFontFamilies).map(([value, family]) => ({
+ value, label: family.label, description: `${family.category} · ${family.intendedUse}`,
+ })),
+ }],
+ };
+}
diff --git a/packages/media-track-studio/src/index.ts b/packages/media-track-studio/src/index.ts
index 4d5a53c0..3a2d887f 100644
--- a/packages/media-track-studio/src/index.ts
+++ b/packages/media-track-studio/src/index.ts
@@ -58,7 +58,7 @@ placeMedia([
placeMedia(["stack-order"], "where", "Frame", "Stacking");
placeMedia(["clip", "radius", "padding"], "where", "Frame", "Geometry");
placeMedia(["opacity", "blur", "brightness", "contrast", "saturation"], "how", "Image", "Image");
-placeMedia(["playback", "trim-start", "trim-end"], "how", "Playback", "Playback");
+placeMedia(["playback", "trim-start", "trim-end"], "when", "Playback", "Playback");
placeMedia(["border-width", "border-style", "border-color", "shadows", "frame-paint"], "how", "Frame", "Paint");
placeMedia(["enter", "enter-frames", "enter-easing", "enter-direction", "enter-amount", "enter-origin"], "when", "Enter", "Enter");
placeMedia(["sustain"], "when", "Sustain", "Sustain");
@@ -66,6 +66,8 @@ placeMedia(["exit", "exit-frames", "exit-easing", "exit-direction", "exit-amount
const mediaColorProperties = new Set(["border-color"]);
const mediaTextProperties = new Set(["padding", "shadows", "frame-paint", "sustain"]);
+const mediaPercentProperties = new Set(["frame-x", "frame-y", "content-x", "content-y", "opacity", "brightness", "contrast", "saturation"]);
+const mediaPixelProperties = new Set(["fit-offset-x", "fit-offset-y", "radius", "blur", "border-width"]);
function mediaRecipe(name: "appearance" | "motion"): {
readonly bindings: readonly { readonly name: string }[];
@@ -88,6 +90,9 @@ function mediaRecipe(name: "appearance" | "motion"): {
...placement,
...(property.summary === undefined ? {} : { summary: property.summary }),
control,
+ ...(mediaPercentProperties.has(property.name) ? { unit: "%", number: { scale: 100, step: 1 } } : {}),
+ ...(mediaPixelProperties.has(property.name) ? { unit: "px", number: { step: 1 } } : {}),
+ ...(["enter-frames", "exit-frames", "trim-start", "trim-end"].includes(property.name) ? { unit: "f", number: { step: 1 } } : {}),
...(options === undefined ? {} : { options }),
};
}),
@@ -209,7 +214,7 @@ export const mediaTrackStudioTrackCompanions: readonly StudioTrackCompanion[] =
...frameParameters.filter(({ writable }) => writable === true).map(({ name }) => ({
binding: `frame.${name}`, label: title(name), domain: "where" as const,
page: { id: frameSizeParameters.has(name) ? "size" : "placement", label: frameSizeParameters.has(name) ? "Size" : "Placement" },
- section: { id: "frame", label: "Frame" }, control: "text" as const,
+ section: { id: "frame", label: "Frame" }, control: "number" as const, number: { suffixes: ["%", "px"], step: 1 },
})),
...extentParameters.map(({ name }) => ({
binding: `extent.${name}`, label: title(name), domain: "where" as const,
diff --git a/packages/ranking-studio/package.json b/packages/ranking-studio/package.json
index e600def4..bf61b4ab 100644
--- a/packages/ranking-studio/package.json
+++ b/packages/ranking-studio/package.json
@@ -4,11 +4,16 @@
"license": "SEE LICENSE IN LICENSE",
"private": true,
"type": "module",
- "exports": { ".": "./src/index.ts" },
- "hypit": { "activation": "./src/activation.ts" },
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "hypit": {
+ "activation": "./src/activation.ts"
+ },
"dependencies": {
"@hypit/ranking": "workspace:*",
"@hypit/composition": "workspace:*",
- "@hypit/studio-adapter": "workspace:*"
+ "@hypit/studio-adapter": "workspace:*",
+ "@hypit/fonts-open": "workspace:*"
}
}
diff --git a/packages/ranking-studio/src/index.ts b/packages/ranking-studio/src/index.ts
index f8924266..e4aa2fb1 100644
--- a/packages/ranking-studio/src/index.ts
+++ b/packages/ranking-studio/src/index.ts
@@ -1,9 +1,13 @@
+import { openFontStudioFields } from "@hypit/fonts-open/studio";
import { rankingMarkupSurfaces, rankingModuleRef, rankingTypes } from "@hypit/ranking";
import type { RankingProgram, RankingSchedule } from "@hypit/ranking";
import { compositionTypes } from "@hypit/composition";
import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-adapter";
import { artifactPreview, authoredChildFor, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
+
+const fontInspector = openFontStudioFields("style");
+
const frameParameters: readonly StudioSourceBindingDeclaration[] = [
{ name: "within" },
...["left", "top", "right", "bottom", "x", "y", "width", "height"].map((name) => ({ name, writable: true })),
@@ -76,7 +80,7 @@ const rankingInspectorPlacement = {
} as const satisfies Readonly<Record<string, RankingInspectorPlacement>>;
function rankingInspector(surface: "column-style" | "tier-style" | "top-three-style"): readonly StudioInspectorFieldDeclaration[] {
- return rankingProperties(surface).map((property) => {
+ return [...fontInspector.fields, ...rankingProperties(surface).map((property) => {
const placement = rankingInspectorPlacement[property.name as keyof typeof rankingInspectorPlacement];
if (placement === undefined) throw new Error(`Ranking Studio has no explicit placement for ${property.name}.`);
return {
@@ -85,12 +89,13 @@ function rankingInspector(surface: "column-style" | "tier-style" | "top-three-st
...placement,
...(property.summary === undefined ? {} : { summary: property.summary }),
};
- });
+ })];
}
function rankingStyle(surface: "column-style" | "tier-style" | "top-three-style"): StudioSourceBindingDeclaration {
return {
name: "style",
+ referenced: [fontInspector.binding],
recipe: { through: ["recipe"], bindings: rankingProperties(surface).map(({ name, schema, fallback }) => ({
name,
schema,
@@ -162,7 +167,7 @@ const frameInspector: readonly StudioInspectorFieldDeclaration[] = frameParamete
.filter(({ writable }) => writable === true)
.map(({ name }) => ({
binding: `frame.${name}`, label: title(name), domain: "where",
- page: { id: "frame", label: "Frame" }, section: { id: "frame", label: "Frame" }, control: "text",
+ page: { id: "frame", label: "Frame" }, section: { id: "frame", label: "Frame" }, control: "number", number: { suffixes: ["%", "px"], step: 1 },
}));
export const rankingStudioTrackCompanions: readonly StudioTrackCompanion[] = [
diff --git a/packages/studio-adapter/README.md b/packages/studio-adapter/README.md
index b5a2814d..ea8324be 100644
--- a/packages/studio-adapter/README.md
+++ b/packages/studio-adapter/README.md
@@ -184,6 +184,11 @@ silently becoming one policy. Studio resolves the declarations against the
current Source closure, publishes only real writable fields, renders all DOM
and CSS itself, and commits changes through `parameter.adjust`.
+Fields can declare `number` display scaling, supported suffixes, limits and step; `unit` alone is
+only a label. Select options can carry separate scalar values, labels, descriptions and color/font
+preview hints. Text may be multiline; colors may offer package-chosen swatches. See
+[Inspector presentation and conversion](../studio/INSPECTOR.md) for examples and ownership.
+
Structured controls keep a local draft and commit one complete canonical value.
Their codec is the author language (`@hypit/svs` for Recipe values), not a
Companion callback. Companions cannot inject DOM, CSS, parsing code or filesystem
diff --git a/packages/studio-adapter/src/index.ts b/packages/studio-adapter/src/index.ts
index c1f5f1ea..b910551a 100644
--- a/packages/studio-adapter/src/index.ts
+++ b/packages/studio-adapter/src/index.ts
@@ -122,6 +122,24 @@ export const studioParameterControls = [
export type StudioParameterControl = typeof studioParameterControls[number];
export type StudioParameterLanguage = "svml" | "svs" | "svrun";
+/** Data-only choices. Packages supply meaning; Studio owns all option rendering. */
+export type StudioParameterOption = string | {
+ readonly value: string | number | boolean;
+ readonly label: string;
+ readonly description?: string;
+ readonly preview?: { readonly kind: "color"; readonly color: string }
+ | { readonly kind: "font"; readonly family: string; readonly sample?: string };
+};
+
+/** Displayed number = authored number × scale. Suffixes are retained, never converted. */
+export type StudioNumberPresentation = {
+ readonly scale?: number;
+ readonly suffixes?: readonly string[];
+ readonly minimum?: number;
+ readonly maximum?: number;
+ readonly step?: number;
+};
+
/** A real author endpoint. Its existence never implies Inspector visibility. */
export type StudioSourceBinding = {
readonly id: string;
@@ -170,8 +188,12 @@ export type StudioInspectorFieldDeclaration = {
readonly summary?: string;
/** Omit when the binding's public schema selects the finite Studio control. */
readonly control?: StudioParameterControl;
- readonly options?: readonly string[];
+ readonly options?: readonly StudioParameterOption[];
readonly unit?: string;
+ readonly number?: StudioNumberPresentation;
+ readonly multiline?: boolean;
+ /** Optional suggested colors, independent of the accepted color value. */
+ readonly swatches?: readonly string[];
};
/** Resolved Inspector DTO. Studio renders it and executes its exact source write. */
diff --git a/packages/studio/INSPECTOR.md b/packages/studio/INSPECTOR.md
new file mode 100644
index 00000000..dd710e0f
--- /dev/null
+++ b/packages/studio/INSPECTOR.md
@@ -0,0 +1,104 @@
+# Companion-owned Inspector fields
+
+The Inspector asks three questions. **Where** describes spatial placement and organization;
+**When** describes scheduling, playback and changes over time; **How** describes appearance,
+content and sound. These are navigation domains, not restrictions on component behavior.
+
+| Domain | Useful pages and sections |
+| --- | --- |
+| Where | Position, size, anchor, fitting/cropping, padding, clipping, stacking, layout |
+| When | Placement in time, playback/cycling, source trim, entrance, sustained motion, exit, transitions, fades |
+| How | Text/content, typography, fill/stroke, image adjustments, shadows, effect character, audio levels |
+
+Each Companion supplies page and section IDs and labels in declaration order. These examples are
+a shared vocabulary, not a registry of permitted pages. A new component can name a useful grouping
+without a Studio change. Put a field where its authoring decision belongs: motion duration is When,
+its color is How, and the object's frame is Where. One field has one owner and one location.
+
+## Controls describe the editing task
+
+`bindings` exposes actual author endpoints; `inspector` chooses which to show. A resolved field is
+shown only when its binding is writable. The finite controls are independent of the three domains:
+
+| Control | Use |
+| --- | --- |
+| `text` | Text, identifiers, or a meaningful expression. `multiline: true` provides a textarea. |
+| `number` | A scalar with optional limits, stepping, display scaling, or an authored suffix. |
+| `boolean` | A two-state switch. |
+| `select` | A finite choice, including presets, font families or numeric weights. |
+| `color` | Hex text and a native color picker; optional `swatches` offers package-chosen colors. |
+| `list` | An ordered value described by an array schema, such as a palette or repeated settings. |
+| `record` | Named values described by an object schema, such as one shadow's parameters. |
+
+Lists and records retain Apply/Reset drafts. Their schema owns value shape. There is no separate
+palette database, font control protocol, generic CSS editor, or component-supplied DOM renderer.
+Use text for an expression whose parts cannot meaningfully be edited as one number.
+
+## Separate author values from display values
+
+The DTO retains the authored `value`. A numeric presentation describes the small, reversible
+conversion into the editor. The server applies the inverse, validates the **authored** value against
+its public schema, and uses the author language's serializer. Source ranges and existing transactions
+still own the write. Failed validation or recompilation does not publish a partial edit.
+
+```ts
+// Authored as "78%" or "240px": edit only the magnitude, keep the existing unit.
+{ binding: "frame.width", label: "Width", domain: "where",
+ section: { id: "size", label: "Size" }, control: "number",
+ number: { suffixes: ["%", "px"], step: 1 } }
+
+// Authored as 0.78: display 78 %, write 0.42 when the author enters 42.
+{ binding: "appearance.opacity", label: "Opacity", domain: "how",
+ section: { id: "image", label: "Image" }, control: "number", unit: "%",
+ number: { scale: 100, minimum: 0, maximum: 100, step: 1 } }
+```
+
+`unit` is a label, not an instruction to append text. `suffixes` explicitly declares a string-valued
+number and retains whichever admitted suffix the current source uses. It does not convert `%` into
+pixels or seconds into frames. `scale` is positive; displayed value = authored magnitude × scale.
+Limits and step in `number` refer to displayed values. A number schema's limits and integer setting
+also inform the input when no presentation override is provided. Empty input is not silently zero.
+
+SVML strings escape attribute delimiters and entity characters. SVS values use `formatSvsValue`.
+Neither the UI nor a Companion writes source text through an arbitrary callback. Timeline temporal
+gestures are separate from Inspector field conversion; see the temporal author forms for their
+semantic-anchor and local-offset editing behavior.
+
+## Choices retain their actual value
+
+Existing string options are shorthand for identical value and label. Rich options can supply a
+different label, description and one small visual hint:
+
+```ts
+options: [
+ { value: "brand-serif", label: "Brand Serif", description: "Project headline face",
+ preview: { kind: "font", family: "Project Serif", sample: "Aa 字幕" } },
+ { value: "brand-sans", label: "Brand Sans" },
+]
+```
+
+A color hint uses `{ kind: "color", color: "#FF584A" }`. Values may be strings, numbers or booleans;
+the selected value, not its display label, is validated and written. Preview hints contain data only.
+Options remain named keyboard-operable choices. Font hints use a family available to the Studio
+document; declaring a hint does not install or load a font or change the composition's font bytes.
+
+The optional `@hypit/fonts-open/studio` helper owns its catalog labels and descriptions. Caption,
+Typography and Ranking Companions use it to reach a Style's referenced font and edit its `family`
+attribute. It appears for an actual writable family attribute; a `media:Font` file has no such
+attribute. The family still has to supply the authored weight and style. A local font keeps its exact
+file binding. Changing a shared font changes every consumer; this is visible Source reuse.
+
+Nested `referenced` declarations follow explicit author references, such as Style → Font → family.
+They neither scan for candidates nor replace whole-value references with strings. Project components
+can declare their own option values and binding paths through the same ABI.
+
+## Implementation owners
+
+- `studio-adapter` owns the data-only declarations and snapshot types.
+- Component Companions own grouping, choices, units and references to writable author facts.
+- Studio resolves endpoints, renders controls, converts display values and commits source edits.
+- SVML/SVS and the component's ordinary compilation remain the authority for valid authored work.
+
+The UI follows native numeric input behavior and named listbox options; reference material:
+[MDN numeric inputs](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/number),
+[WAI listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/).
diff --git a/packages/studio/README.md b/packages/studio/README.md
index 3756712f..929180e8 100644
--- a/packages/studio/README.md
+++ b/packages/studio/README.md
@@ -99,11 +99,25 @@ Timeline gestures use explicit temporal authority. Moving a shared Selection or
Moment edits Script and moves its consumers after recompilation. A parameter-based
handle edits its exact authored parameter. Fixed or derived values with no supported
inverse remain read-only. Seeing an entity does not promise every drag gesture.
+
+A direct `during={selection}` move advances both endpoints by the same number of semantic
+stops (distinct frame positions), so its duration may change. `at/for` moves its event and
+offers a trailing duration trim; `until/for` offers the corresponding leading trim.
+An Instant reference expression edits only its offset; a bare reference has an implicit zero offset.
+`start/end` trims edit the corresponding expression; moving the window shifts both by the same
+frame delta. Edited clock values and offsets are written in frames at the current ProgramSpace rate.
+The semantic marker Inspector exposes exact anchor identities and, where a
+declared handle supports it, offers choices among coincident anchors.
+See [temporal author forms](../temporal-markup/EDITING.md) for the complete behavior.
+
Tasks and Artifacts are inspection surfaces; selecting an Artifact does not write a
Run Candidate. Use `build-record`/`satisfy` in the Run for explicit Output reuse.
## Component presentation
+[Inspector fields](INSPECTOR.md) describes Where/When/How grouping, numeric unit conversion,
+rich choices, fonts, color suggestions and exact Source writeback.
+
Studio is an application boundary. Core and domain computation do not import it or
register UI metadata. The installed Distribution explicitly selects one independent
Studio Companion per supported official domain. Packages actually selected by the
diff --git a/packages/studio/src/parameter-values.ts b/packages/studio/src/parameter-values.ts
index bb5a5d03..5b26e8a9 100644
--- a/packages/studio/src/parameter-values.ts
+++ b/packages/studio/src/parameter-values.ts
@@ -1,5 +1,44 @@
import type { CanonicalValue, ValueSchema } from "@hypit/protocol";
import { formatSvsValue } from "@hypit/svs";
+import type { StudioInspectorField, StudioParameterOption, StudioNumberPresentation } from "@hypit/studio-adapter";
+
+export const parameterOption = (option: StudioParameterOption): Exclude<StudioParameterOption, string> =>
+ typeof option === "string" ? { value: option, label: option } : option;
+
+// Keep binary floating-point residue out of decimal controls (0.55 × 100 is 55).
+const scaledDecimal = (value: number, scale: number): number =>
+ scale === 1 ? value : Number((value * scale).toPrecision(15));
+
+export function parameterNumber(value: CanonicalValue, presentation: StudioNumberPresentation = {}): { value: number; suffix: string } {
+ let held = value;
+ let suffix = "";
+ if (presentation.suffixes !== undefined) {
+ if (typeof held !== "string") throw new Error("A suffixed number must be authored as text.");
+ const text = held.trim();
+ const found = [...presentation.suffixes].sort((a, b) => b.length - a.length).find(item => text.endsWith(item));
+ if (found === undefined) throw new Error("The authored unit is not supported by this field.");
+ suffix = found;
+ held = text.slice(0, text.length - suffix.length).trim();
+ }
+ if (typeof held !== "number" && (typeof held !== "string" || !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/iu.test(held.trim()))) {
+ throw new Error("This field needs a numeric value.");
+ }
+ const number = scaledDecimal(Number(held), presentation.scale ?? 1);
+ if (!Number.isFinite(number)) throw new Error("This field needs a finite number.");
+ return { value: number, suffix };
+}
+
+/** Decode the displayed edit before validating and serializing the authored value. */
+export function parameterAuthorValue(field: StudioInspectorField, displayed: CanonicalValue): CanonicalValue {
+ if (field.control !== "number") return displayed;
+ if (typeof displayed !== "number" || !Number.isFinite(displayed)) throw new Error(`${field.label} expects a finite number.`);
+ const presentation = field.number ?? {};
+ if (presentation.minimum !== undefined && displayed < presentation.minimum) throw new Error(`${field.label} must be at least ${presentation.minimum}.`);
+ if (presentation.maximum !== undefined && displayed > presentation.maximum) throw new Error(`${field.label} must be at most ${presentation.maximum}.`);
+ const value = scaledDecimal(displayed, 1 / (presentation.scale ?? 1));
+ if (!Number.isFinite(value)) throw new Error(`${field.label} cannot be represented.`);
+ return presentation.suffixes === undefined ? value : `${value}${parameterNumber(field.value, presentation).suffix}`;
+}
function fail(path: string, expectation: string): never {
throw new Error(`${path} ${expectation}.`);
@@ -76,6 +115,7 @@ export function validateParameterValue(value: CanonicalValue, schema: ValueSchem
export function serializeParameterValue(value: CanonicalValue, language: "svml" | "svs" | "svrun"): string {
if (language === "svs") return formatSvsValue(value);
- if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return String(value);
+ if (typeof value === "string") return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&apos;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+ if (typeof value === "number" || typeof value === "boolean") return String(value);
throw new Error(`${language.toUpperCase()} parameter bindings currently accept scalar values only.`);
}
diff --git a/packages/studio/src/parameters.ts b/packages/studio/src/parameters.ts
index 174ed6c5..e0720cfe 100644
--- a/packages/studio/src/parameters.ts
+++ b/packages/studio/src/parameters.ts
@@ -238,8 +238,16 @@ function referencedParameters(input: {
const file = sourceFor(input.root, target.sourcePath, input.files);
if (file === undefined) return [];
return input.declarations.flatMap((declaration) => {
+ const nestedPath = target.references[declaration.name];
+ const nested = nestedPath === undefined || declaration.referenced === undefined ? [] : referencedParameters({
+ root: input.root, files: input.files, draft: input.draft, placements: input.placements,
+ referenceName: `${input.referenceName}.${declaration.name}`,
+ referencePath: nestedPath,
+ ...(target.resolvedReferences[declaration.name] === undefined ? {} : { referenceRef: target.resolvedReferences[declaration.name] }),
+ declarations: declaration.referenced,
+ });
const range = target.attributeValueRanges[declaration.name];
- if (range === undefined) return [];
+ if (range === undefined) return nested;
const preimage = file.text.slice(range.start, range.end);
const reference = target.references[declaration.name];
const value = reference === undefined ? (target.attributes[declaration.name] ?? preimage) : reference;
@@ -263,7 +271,7 @@ function referencedParameters(input: {
...(!writable
? { disabledReason: reference === undefined ? "该几何值由组件声明为只读。" : "引用由作者在 SVML 中绑定,面板不替换引用关系。" }
: {}),
- } satisfies StudioSourceBinding];
+ } satisfies StudioSourceBinding, ...nested];
});
}
@@ -484,7 +492,7 @@ export function resolveTimelineEditHandles(
moveEffect?: "translate-window" | "move-start",
): StudioEditHandle => {
const unavailable = affected.find(({ endpoint }) => endpoint.authority.kind === "fixed");
- if (unavailable !== undefined) return disabled(gesture, "该端点由 Program 或 Segment 结构固定,不能从组件时间线反写。");
+ if (unavailable !== undefined) return disabled(gesture, "该时间表达未开放时间轴回写。");
const projected: ({ readonly missing: string } | StudioEditSource)[] = [];
for (const { endpoint, role } of affected) {
if (endpoint.authority.kind !== "parameter") continue;
@@ -527,24 +535,15 @@ export function resolveTimelineEditHandles(
}
const start = { endpoint: projection.start, role: "start" as const };
const end = { endpoint: projection.end, role: "end" as const };
- const move = projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start"
- ? [start]
- : projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end"
- ? [end]
- : [start, end];
- const trimStart = projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end"
- ? [start]
- : projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start"
- ? [start, end]
- : [start];
- const trimEnd = projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start"
- ? [end]
- : projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end"
- ? [start, end]
- : [end];
+ if (projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start") {
+ return [handle("move", [start], "translate-window"), handle("trim-end", [end])];
+ }
+ if (projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end") {
+ return [handle("move", [end], "translate-window"), handle("trim-start", [start])];
+ }
return [
- handle("move", move, "translate-window"),
- handle("trim-start", trimStart),
- handle("trim-end", trimEnd),
+ handle("move", [start, end], "translate-window"),
+ handle("trim-start", [start]),
+ handle("trim-end", [end]),
];
}
diff --git a/packages/studio/src/server.ts b/packages/studio/src/server.ts
index fbf970d1..a624945d 100644
--- a/packages/studio/src/server.ts
+++ b/packages/studio/src/server.ts
@@ -15,12 +15,13 @@ import type { ServedFile } from "./compile.js";
import type { StudioDomain } from "./domain.js";
import type { StudioCompanionRegistry } from "./studio-registry.js";
import { loadStudioRun } from "./run.js";
-import { serializeParameterValue, validateParameterValue } from "./parameter-values.js";
+import { parameterAuthorValue, parameterOption, serializeParameterValue, validateParameterValue } from "./parameter-values.js";
import { readStudioSession } from "./session.js";
import type { Range, StudioFailure, StudioLibraryRequest, StudioLibraryView, StudioMutation, StudioSnapshot } from "./shared.js";
import { createStudioStoryboard } from "./storyboard.js";
import type { StudioStoryboard } from "./storyboard.js";
import { findSurfacePreview } from "./surface-preview.js";
+import { formatTemporalPointEdit, semanticGestureSpan } from "./temporal-edit.js";
import { replaceSourceFiles } from "./source-transaction.js";
export type StudioPluginOptions = {
@@ -272,7 +273,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
throw new Error("A timeline target must use valid whole frames.");
}
if (temporal.kind === "window") {
- if (mutation.gesture === "move"
+ if (mutation.gesture === "move" && handle.semantic?.kind !== "selection"
&& endFrameExclusive - startFrame !== clip.endFrameExclusive - clip.startFrame) {
throw new Error("Move must preserve the Window duration.");
}
@@ -288,6 +289,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
const patches: Patch[] = [];
const semanticTarget = mutation.target.semantic;
+ if (handle.semantic !== undefined && semanticTarget === undefined) throw new Error("A semantic edit requires explicit target anchors.");
if (semanticTarget !== undefined) {
if (handle.semantic?.kind !== semanticTarget.kind) {
throw new Error(`Entity ${mutation.entityId} is not bound to a writable ${semanticTarget.kind}.`);
@@ -299,15 +301,9 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
|| script.narrativeId !== current.semantic.narrativeId) {
throw new Error("The timeline entity and writable Script do not belong to the selected Narrative.");
}
- if (semanticTarget.kind === "selection") {
- const startIndex = current.semantic.anchors.findIndex((anchor) => anchor.id === semanticTarget.startAnchorId);
- const endIndex = current.semantic.anchors.findIndex((anchor) => anchor.id === semanticTarget.endAnchorId);
- if (startIndex < 0 || endIndex < 0 || startIndex >= endIndex
- || current.semantic.anchors[startIndex]!.frame >= current.semantic.anchors[endIndex]!.frame) {
- throw new Error("A Selection must span two ordered semantic Anchors with positive time.");
- }
- } else if (!current.semantic.anchors.some((anchor) => anchor.id === semanticTarget.anchorId)) {
- throw new Error(`Moment Anchor ${semanticTarget.anchorId} does not exist in the current semantic Candidate.`);
+ const projected = semanticGestureSpan(current.semantic.anchors, handle, semanticTarget);
+ if (projected === undefined || projected.startFrame !== startFrame || projected.endFrameExclusive !== endFrameExclusive) {
+ throw new Error("The semantic edit does not produce the requested timeline projection.");
}
const absolute = resolve(options.workspaceRoot, script.sourcePath);
const source = await readFile(absolute, "utf8");
@@ -367,20 +363,15 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
}
return snapshot?.semantic?.moments.find((candidate) => candidate.id === id)?.frame;
};
- const projectedPointValue = (endpoint: StudioTemporalInstantProjection, desired: number): string => {
- if (endpoint.reference === "absolute") return frame(desired);
- const base = projectionBaseFrame(endpoint);
- if (base === undefined) throw new Error(`The ${endpoint.reference} projection base is unavailable.`);
- const offset = desired - base;
- return offset === 0 ? endpoint.reference : `${endpoint.reference}${offset > 0 ? "+" : ""}${offset}f`;
- };
+ const projectedPointValue = (endpoint: StudioTemporalInstantProjection, desired: number): string =>
+ formatTemporalPointEdit(endpoint.reference, desired, projectionBaseFrame(endpoint));
const writeEndpoint = (
endpoint: StudioTemporalInstantProjection,
desired: number,
role: "start" | "end",
): void => {
if (desired === endpoint.frame) return;
- if (endpoint.authority.kind === "fixed") throw new Error(`The ${role} endpoint is structurally fixed.`);
+ if (endpoint.authority.kind === "fixed") throw new Error(`The ${role} endpoint has no timeline write target.`);
if (endpoint.authority.kind === "semantic") {
if (semanticFrame(endpoint) !== desired) throw new Error(`The ${role} endpoint does not match its semantic Anchor.`);
return;
@@ -414,20 +405,22 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
if (parameter === undefined) {
throw new Error(`Entity ${mutation.entityId} has no writable parameter ${mutation.parameterId}.`);
}
+ const authorValue = parameterAuthorValue(parameter, mutation.value);
if (parameter.schema !== undefined) {
- validateParameterValue(mutation.value, parameter.schema, parameter.label);
+ validateParameterValue(authorValue, parameter.schema, parameter.label);
} else if (parameter.control === "boolean" && typeof mutation.value !== "boolean") {
throw new Error(`${parameter.label} expects true or false.`);
} else if (parameter.control === "number" && (typeof mutation.value !== "number" || !Number.isFinite(mutation.value))) {
throw new Error(`${parameter.label} expects a number.`);
- } else if ((parameter.control === "text" || parameter.control === "color" || parameter.control === "select")
+ } else if ((parameter.control === "text" || parameter.control === "color")
&& typeof mutation.value !== "string") {
throw new Error(`${parameter.label} expects text.`);
}
- if (parameter.options !== undefined && (typeof mutation.value !== "string" || !parameter.options.includes(mutation.value))) {
+ if (parameter.options !== undefined && !parameter.options.some(option => parameterOption(option).value === authorValue)) {
throw new Error(`${parameter.label} does not accept ${mutation.value}.`);
}
- const encoded = serializeParameterValue(mutation.value, parameter.language);
+ if (parameter.control === "color") validateParameterValue(authorValue, { kind: "string", format: "color" }, parameter.label);
+ const encoded = serializeParameterValue(authorValue, parameter.language);
const replacement = `${parameter.source.prefix ?? ""}${encoded}${parameter.source.suffix ?? ""}`;
return replacement === parameter.source.preimage ? [] : [{
...parameter.source,
diff --git a/packages/studio/src/studio-registry.ts b/packages/studio/src/studio-registry.ts
index b536abd2..320619cf 100644
--- a/packages/studio/src/studio-registry.ts
+++ b/packages/studio/src/studio-registry.ts
@@ -14,6 +14,7 @@ import type {
StudioSpan,
} from "@hypit/studio-adapter";
import { studioParameterControls } from "@hypit/studio-adapter";
+import { parameterOption } from "./parameter-values.js";
import { compositionTypes } from "@hypit/composition";
import { sameModule, sameType } from "@hypit/protocol";
import type { ModuleRef, TypeRef } from "@hypit/protocol";
@@ -67,6 +68,27 @@ function validateInspector(
if (field.control === "select" && (field.options === undefined || field.options.length === 0)) {
throw new Error(`${subject} Inspector field ${field.binding} has no select options`);
}
+ const choices = (field.options ?? []).map(parameterOption);
+ if (choices.some(option => !option.label.trim() || !["string", "number", "boolean"].includes(typeof option.value)
+ || typeof option.value === "number" && !Number.isFinite(option.value))
+ || new Set(choices.map(option => JSON.stringify(option.value))).size !== choices.length) {
+ throw new Error(`${subject} Inspector field ${field.binding} has invalid or repeated choices`);
+ }
+ const numeric = field.number;
+ if (numeric !== undefined) {
+ if (field.control !== "number" || numeric.scale !== undefined && (!Number.isFinite(numeric.scale) || numeric.scale <= 0)
+ || numeric.step !== undefined && (!Number.isFinite(numeric.step) || numeric.step <= 0)
+ || numeric.minimum !== undefined && !Number.isFinite(numeric.minimum)
+ || numeric.maximum !== undefined && !Number.isFinite(numeric.maximum)
+ || numeric.minimum !== undefined && numeric.maximum !== undefined && numeric.minimum > numeric.maximum
+ || numeric.suffixes !== undefined && (numeric.suffixes.length === 0 || numeric.suffixes.some(suffix => !suffix.trim()))) {
+ throw new Error(`${subject} Inspector field ${field.binding} has an invalid numeric presentation`);
+ }
+ }
+ if (field.multiline && field.control !== "text") throw new Error(`${subject} multiline editing requires text`);
+ if (field.swatches !== undefined && (field.control !== "color" || field.swatches.some(color => !/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(color)))) {
+ throw new Error(`${subject} color suggestions require hex colors`);
+ }
}
}
diff --git a/packages/studio/src/style.css b/packages/studio/src/style.css
index 4a23f808..28031391 100644
--- a/packages/studio/src/style.css
+++ b/packages/studio/src/style.css
@@ -863,6 +863,7 @@ button:focus-visible, textarea:focus-visible {
box-shadow: 0 10px 26px rgba(0, 0, 0, .42);
}
.parameter-select.open-up .parameter-select-menu { top: auto; bottom: calc(100% + 4px); }
+.parameter-select.rich-options .parameter-select-menu { width: 240px; max-height: 240px; }
.parameter-select-menu[hidden] { display: none; }
.parameter-select-option {
width: 100%;
@@ -880,6 +881,19 @@ button:focus-visible, textarea:focus-visible {
.parameter-select-option.active { background: #202226; color: #d5d7dc; }
.parameter-select-option:focus-visible { outline: 0; background: #292b30; color: var(--text); }
.parameter-right > small { flex: none; color: var(--text-3); font-size: 10px; }
+.parameter-value[type="number"] { appearance: textfield; }
+.parameter-value[type="number"]::-webkit-inner-spin-button { opacity: .55; }
+.parameter-value:invalid { border-color: #a45c60; }
+.parameter-value[readonly] { color: var(--text-3); }
+.parameter-multiline { min-height: 64px; resize: vertical; text-align: left; line-height: 1.5; }
+.parameter-select-option { padding: 6px 8px; white-space: normal; text-align: left; }
+.parameter-select-option > small { display: block; margin-top: 3px; color: var(--text-3); font: 10px/1.4 var(--font-ui); }
+.parameter-option-swatch { display: inline-block; width: 12px; height: 12px; margin-right: 7px; border-radius: 2px; vertical-align: middle; box-shadow: inset 0 0 0 1px #ffffff22; }
+.parameter-option-font { display: block; margin-top: 4px; font-size: 18px; }
+.control-color .parameter-right { flex-wrap: wrap; }
+.parameter-swatches { display: flex; flex-wrap: wrap; gap: 5px; padding-top: 3px; }
+.parameter-swatches button { width: 18px; height: 18px; border: 1px solid #ffffff22; border-radius: 3px; }
+.parameter-swatches button:focus-visible { outline: 1px solid var(--text); outline-offset: 2px; }
.status.saving { color: var(--text-2); }
.status.saved { color: var(--ok); }
diff --git a/packages/studio/src/temporal-edit.ts b/packages/studio/src/temporal-edit.ts
new file mode 100644
index 00000000..e9bcf413
--- /dev/null
+++ b/packages/studio/src/temporal-edit.ts
@@ -0,0 +1,131 @@
+import type { StudioEditHandle, StudioSemanticAnchor, StudioTemporalInstantProjection } from "@hypit/studio-adapter";
+
+export type SemanticTarget =
+ | { readonly kind: "selection"; readonly startAnchorId: string; readonly endAnchorId: string }
+ | { readonly kind: "moment"; readonly anchorId: string };
+
+type Span = { readonly startFrame: number; readonly endFrameExclusive: number };
+
+/** Project only the semantic write exposed by the handle. This does not invert expressions. */
+export function semanticGestureSpan(
+ anchors: readonly StudioSemanticAnchor[], handle: StudioEditHandle, target: SemanticTarget,
+): Span | undefined {
+ const semantic = handle.semantic;
+ const temporal = handle.temporal;
+ if (!semantic || !temporal || target.kind !== semantic.kind) return undefined;
+ const byId = new Map(anchors.map((anchor, order) => [anchor.id, { ...anchor, order }]));
+ let span: Span;
+ if (semantic.kind === "moment" && target.kind === "moment") {
+ const previous = byId.get(semantic.anchorId);
+ const next = byId.get(target.anchorId);
+ if (!previous || !next) return undefined;
+ const delta = next.frame - previous.frame;
+ span = temporal.kind === "instant"
+ ? { startFrame: temporal.frame + delta, endFrameExclusive: temporal.frame + delta + 1 }
+ : { startFrame: temporal.startFrame + delta, endFrameExclusive: temporal.endFrameExclusive + delta };
+ } else if (semantic.kind === "selection" && target.kind === "selection") {
+ const start = byId.get(target.startAnchorId);
+ const end = byId.get(target.endAnchorId);
+ if (!start || !end || start.order > end.order) return undefined;
+ if (temporal.kind === "instant") {
+ if (temporal.authority.kind !== "semantic") return undefined;
+ if (temporal.authority.boundary === "start" && target.endAnchorId !== semantic.endAnchorId
+ || temporal.authority.boundary === "end" && target.startAnchorId !== semantic.startAnchorId) return undefined;
+ const frame = temporal.authority.boundary === "start" ? start.frame : end.frame;
+ span = { startFrame: frame, endFrameExclusive: frame + 1 };
+ } else {
+ if (handle.gesture === "trim-start" && target.endAnchorId !== semantic.endAnchorId
+ || handle.gesture === "trim-end" && target.startAnchorId !== semantic.startAnchorId) return undefined;
+ if (handle.gesture === "move") {
+ const stops = [...new Set(anchors.map((anchor) => anchor.frame))].sort((a, b) => a - b);
+ const previousStart = byId.get(semantic.startAnchorId);
+ const previousEnd = byId.get(semantic.endAnchorId);
+ if (!previousStart || !previousEnd
+ || stops.indexOf(start.frame) - stops.indexOf(previousStart.frame)
+ !== stops.indexOf(end.frame) - stops.indexOf(previousEnd.frame)) return undefined;
+ }
+ span = { startFrame: start.frame, endFrameExclusive: end.frame };
+ }
+ } else return undefined;
+ if (!Number.isSafeInteger(span.startFrame) || span.startFrame < 0
+ || !Number.isSafeInteger(span.endFrameExclusive) || span.endFrameExclusive <= span.startFrame) return undefined;
+ if (temporal.kind === "window"
+ && ((handle.gesture === "trim-start" && span.endFrameExclusive !== temporal.endFrameExclusive)
+ || (handle.gesture === "trim-end" && span.startFrame !== temporal.startFrame))) return undefined;
+ return span;
+}
+
+/** A stop is a frame position; coincident anchors remain distinct choices at that stop. */
+export function chooseSemanticGesture(input: {
+ readonly anchors: readonly StudioSemanticAnchor[];
+ readonly handle: StudioEditHandle;
+ readonly pointerStart: number;
+ readonly pointerNow: number;
+ readonly frameCount: number;
+}): SemanticTarget | undefined {
+ const { anchors, handle } = input;
+ const semantic = handle.semantic;
+ const temporal = handle.temporal;
+ if (!semantic || !temporal) return undefined;
+ const order = new Map(anchors.map((anchor, index) => [anchor.id, index]));
+ const byId = new Map(anchors.map((anchor) => [anchor.id, anchor]));
+ const at = new Map<number, StudioSemanticAnchor[]>();
+ for (const anchor of anchors) at.set(anchor.frame, [...at.get(anchor.frame) ?? [], anchor]);
+ const stops = [...at.keys()].sort((a, b) => a - b);
+ const ranked = (choices: readonly StudioSemanticAnchor[], preferred: StudioSemanticAnchor) => [...choices].sort((a, b) =>
+ Number(a.id !== preferred.id) - Number(b.id !== preferred.id)
+ || Number(a.kind !== preferred.kind) - Number(b.kind !== preferred.kind)
+ || order.get(a.id)! - order.get(b.id)!);
+ const valid = (target: SemanticTarget) => {
+ const span = semanticGestureSpan(anchors, handle, target);
+ return span !== undefined && (temporal.kind === "instant" ? span.startFrame : span.endFrameExclusive) <= input.frameCount;
+ };
+ const delta = input.pointerNow - input.pointerStart;
+ if (semantic.kind === "moment") {
+ const current = byId.get(semantic.anchorId);
+ if (!current) return undefined;
+ const candidates = ranked(anchors, current).sort((a, b) =>
+ Math.abs(a.frame - current.frame - delta) - Math.abs(b.frame - current.frame - delta));
+ return candidates.map((anchor): SemanticTarget => ({ kind: "moment", anchorId: anchor.id })).find(valid);
+ }
+ const start = byId.get(semantic.startAnchorId);
+ const end = byId.get(semantic.endAnchorId);
+ if (!start || !end) return undefined;
+ const target = (a: StudioSemanticAnchor, b: StudioSemanticAnchor): SemanticTarget => ({
+ kind: "selection", startAnchorId: a.id, endAnchorId: b.id,
+ });
+ if (handle.gesture === "move" && temporal.kind === "window") {
+ const first = stops.indexOf(start.frame);
+ const last = stops.indexOf(end.frame);
+ const shifts = stops.map((_, index) => index - first)
+ .filter((shift) => last + shift >= 0 && last + shift < stops.length)
+ .sort((a, b) => Math.abs(stops[first + a]! - start.frame - delta)
+ - Math.abs(stops[first + b]! - start.frame - delta) || Math.abs(a) - Math.abs(b));
+ for (const shift of shifts) {
+ for (const a of ranked(at.get(stops[first + shift]!)!, start)) {
+ for (const b of ranked(at.get(stops[last + shift]!)!, end)) {
+ const candidate = target(a, b);
+ if (valid(candidate)) return candidate;
+ }
+ }
+ }
+ return undefined;
+ }
+ const boundary = temporal.kind === "instant" && temporal.authority.kind === "semantic"
+ ? temporal.authority.boundary : handle.gesture === "trim-start" ? "start" : "end";
+ const current = boundary === "start" ? start : end;
+ const candidates = ranked(anchors, current).sort((a, b) =>
+ Math.abs(a.frame - current.frame - delta) - Math.abs(b.frame - current.frame - delta));
+ return candidates.map((anchor) => boundary === "start" ? target(anchor, end) : target(start, anchor)).find(valid);
+}
+
+
+/** Keep the reference and write its local frame offset; a bare reference starts at zero. */
+export function formatTemporalPointEdit(
+ reference: StudioTemporalInstantProjection["reference"], desired: number, base?: number,
+): string {
+ if (reference === "absolute") return `${desired}f`;
+ if (base === undefined) throw new Error(`The ${reference} projection base is unavailable.`);
+ const offset = desired - base;
+ return `${reference}${offset >= 0 ? "+" : ""}${offset}f`;
+}
diff --git a/packages/studio/src/ui/main.ts b/packages/studio/src/ui/main.ts
index 81beb63b..76bc1790 100644
--- a/packages/studio/src/ui/main.ts
+++ b/packages/studio/src/ui/main.ts
@@ -1,6 +1,6 @@
import type { Clip, StudioFailure, StudioInspectorDomain, StudioSnapshot } from "../shared.js";
import type { CanonicalValue, ValueSchema } from "@hypit/protocol";
-import { validateParameterValue } from "../parameter-values.js";
+import { parameterAuthorValue, parameterNumber, parameterOption, validateParameterValue } from "../parameter-values.js";
import { createCodePane } from "./code.js";
import { icon } from "./icons.js";
import { createLibraryPane } from "./library.js";
@@ -9,6 +9,8 @@ import type { Highlight } from "./code.js";
import { intentAtOffset, spanAtOffset } from "./markers.js";
import { clipAtOffset, createStore } from "./selection.js";
import { createStage } from "./stage.js";
+import { semanticGestureSpan } from "../temporal-edit.js";
+import type { SemanticTarget } from "../temporal-edit.js";
import { applyStudioMutation } from "./writeback.js";
import { createTimeline } from "./timeline.js";
import "../style.css";
@@ -193,8 +195,13 @@ function textValue(value: CanonicalValue): string {
}
function commitControl(entityId: string, parameter: Clip["inspector"][number], replacement: CanonicalValue): void {
- if (sameValue(replacement, parameter.value)) return;
- void writeParameter(entityId, parameter, replacement);
+ try {
+ if (sameValue(parameterAuthorValue(parameter, replacement), parameter.value)) return;
+ void writeParameter(entityId, parameter, replacement);
+ } catch (error) {
+ status.textContent = "Invalid value"; status.className = "status error";
+ status.title = error instanceof Error ? error.message : String(error);
+ }
}
let openColorPicker: {
@@ -228,8 +235,11 @@ function selectControl(
trigger.setAttribute("aria-expanded", "false");
const selected = document.createElement("span");
selected.className = "parameter-select-value";
- const current = textValue(parameter.value);
- selected.textContent = current;
+ const choices = (parameter.options ?? []).map(parameterOption);
+ if (choices.some(option => option.description || option.preview)) control.classList.add("rich-options");
+ const current = choices.find(option => option.value === parameter.value)
+ ?? choices.find(option => String(option.value) === String(parameter.value));
+ selected.textContent = current?.label ?? textValue(parameter.value);
const chevron = document.createElement("span");
chevron.className = "parameter-select-chevron";
chevron.innerHTML = icon("chevron");
@@ -243,22 +253,32 @@ function selectControl(
menu.hidden = true;
trigger.setAttribute("aria-controls", menu.id);
- const options = (parameter.options ?? []).map((option) => {
+ const options = choices.map((option) => {
const item = document.createElement("button");
item.type = "button";
item.className = `parameter-select-option${option === current ? " active" : ""}`;
- item.textContent = option;
+ const label = document.createElement("span"); label.textContent = option.label;
+ item.append(label);
+ if (option.description) { const description = document.createElement("small"); description.textContent = option.description; item.append(description); }
+ if (option.preview?.kind === "color") {
+ const swatch = document.createElement("span"); swatch.className = "parameter-option-swatch";
+ swatch.style.backgroundColor = option.preview.color; item.prepend(swatch);
+ } else if (option.preview?.kind === "font") {
+ const sample = document.createElement("span"); sample.className = "parameter-option-font";
+ sample.style.fontFamily = option.preview.family; sample.textContent = option.preview.sample ?? option.label;
+ sample.setAttribute("aria-hidden", "true"); item.append(sample);
+ }
item.setAttribute("role", "option");
item.setAttribute("aria-selected", String(option === current));
item.addEventListener("click", () => {
- selected.textContent = option;
+ selected.textContent = option.label;
for (const sibling of options) {
sibling.classList.toggle("active", sibling === item);
sibling.setAttribute("aria-selected", String(sibling === item));
}
close(false);
trigger.focus();
- commitControl(entityId, parameter, option);
+ commitControl(entityId, parameter, option.value);
});
return item;
});
@@ -359,7 +379,7 @@ function colorValueControl(
value.value = initial;
value.setAttribute("aria-label", label);
value.spellcheck = false;
- const alpha = exact && initial.length === 9 ? initial.slice(7) : "";
+ let alpha = exact && initial.length === 9 ? initial.slice(7) : "";
const replacement = (): string => `${picker.value.toUpperCase()}${alpha}`;
const close = (): void => {
if (openColorPicker?.root === colorControl) openColorPicker = undefined;
@@ -390,7 +410,12 @@ function colorValueControl(
});
value.addEventListener(draft ? "input" : "change", () => {
const next = value.value.trim();
- swatch.style.background = /^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(next) ? next : "transparent";
+ const valid = /^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(next);
+ swatch.style.background = valid ? next : "transparent";
+ if (valid) {
+ picker.value = next.slice(0, 7);
+ alpha = next.length === 9 ? next.slice(7) : "";
+ }
change(next);
});
colorControl.append(swatch, picker);
@@ -612,40 +637,71 @@ function parameterControl(entityId: string, parameter: Clip["inspector"][number]
name.title = parameter.summary ?? parameter.label;
const right = document.createElement("span");
right.className = "parameter-right parameter-control";
+ let unitLabel = parameter.unit;
if (parameter.control === "select") {
right.append(selectControl(entityId, parameter));
} else if (parameter.control === "color") {
right.append(colorValueControl(parameter.label, textValue(parameter.value), (next) => {
commitControl(entityId, parameter, next);
}));
+ if (parameter.swatches?.length) {
+ const palette = document.createElement("span"); palette.className = "parameter-swatches";
+ for (const color of parameter.swatches) {
+ const swatch = document.createElement("button"); swatch.type = "button";
+ swatch.style.backgroundColor = color; swatch.title = color; swatch.setAttribute("aria-label", `Use ${color}`);
+ swatch.addEventListener("click", () => commitControl(entityId, parameter, color)); palette.append(swatch);
+ }
+ right.append(palette);
+ }
} else if (parameter.control === "list" || parameter.control === "record") {
right.append(structuredControl(entityId, parameter));
} else {
+ if (parameter.multiline && parameter.control === "text") {
+ const value = document.createElement("textarea"); value.className = "parameter-value parameter-multiline";
+ value.value = textValue(parameter.value); value.setAttribute("aria-label", parameter.label);
+ value.addEventListener("change", () => commitControl(entityId, parameter, value.value)); right.append(value);
+ row.append(name, right); return row;
+ }
const value = document.createElement("input");
value.type = parameter.control === "boolean" ? "checkbox" : "text";
- if (parameter.control === "number") value.inputMode = "decimal";
value.className = "parameter-value";
value.setAttribute("aria-label", parameter.label);
value.spellcheck = false;
if (value.type === "checkbox") value.checked = parameter.value === true || parameter.value === "true";
- else value.value = textValue(parameter.value);
+ else if (parameter.control === "number") {
+ try {
+ const numeric = parameterNumber(parameter.value, parameter.number);
+ value.type = "number"; value.inputMode = "decimal"; value.value = String(numeric.value);
+ const schema = parameter.schema?.kind === "number" ? parameter.schema : undefined;
+ const scale = parameter.number?.scale ?? 1;
+ const minimum = parameter.number?.minimum ?? (schema?.minimum === undefined ? undefined : schema.minimum * scale);
+ const maximum = parameter.number?.maximum ?? (schema?.maximum === undefined ? undefined : schema.maximum * scale);
+ value.step = String(parameter.number?.step ?? (schema?.integer ? scale : "any"));
+ if (minimum !== undefined) value.min = String(minimum);
+ if (maximum !== undefined) value.max = String(maximum);
+ value.required = true;
+ unitLabel = numeric.suffix || parameter.unit;
+ } catch (error) {
+ value.value = textValue(parameter.value); value.readOnly = true;
+ value.title = error instanceof Error ? error.message : String(error);
+ }
+ } else value.value = textValue(parameter.value);
value.dataset.parameterId = parameter.id;
- value.title = parameter.summary ?? parameter.label;
+ if (!value.title) value.title = parameter.summary ?? parameter.label;
value.addEventListener("change", () => {
if (value.type === "checkbox") {
commitControl(entityId, parameter, value.checked);
} else if (parameter.control === "number") {
- const number = Number(value.value);
- if (Number.isFinite(number)) commitControl(entityId, parameter, number);
+ if (value.reportValidity()) commitControl(entityId, parameter, value.valueAsNumber);
} else {
commitControl(entityId, parameter, value.value);
}
});
right.append(value);
}
- if (parameter.unit !== undefined) {
+ if (unitLabel !== undefined) {
const unit = document.createElement("small");
- unit.textContent = parameter.unit;
+ unit.textContent = unitLabel;
right.append(unit);
}
row.append(name, right);
@@ -689,6 +745,7 @@ async function writeParameter(entityId: string, parameter: Clip["inspector"][num
parameterWriteState = "Failed";
status.textContent = error instanceof Error ? "Save failed" : parameterWriteState;
status.className = "status error";
+ status.title = error instanceof Error ? error.message : String(error);
}
}
@@ -785,24 +842,76 @@ function renderSemanticInspector(snapshot: StudioSnapshot, segmentId: string): v
inspector.replaceChildren(empty);
}
+/** Exact identity choice for coincident anchors, through the same Companion-declared handles. */
+function semanticAnchorInspector(snapshot: StudioSnapshot, kind: "selection" | "moment", id: string): HTMLElement {
+ const semantic = snapshot.semantic;
+ const consumers = snapshot.tracks.flatMap((track) => track.clips).flatMap((clip) => clip.editHandles
+ .filter((handle) => handle.enabled && handle.semantic?.kind === kind && handle.semantic.id === id)
+ .map((handle) => ({ clip, handle })));
+ const current = kind === "selection" ? semantic?.selections.find((item) => item.id === id)
+ : semantic?.moments.find((item) => item.id === id);
+ if (!semantic || !current) return group("Timing", []);
+ const endpoints = "anchorId" in current ? [["Moment", current.anchorId]]
+ : [["Start", current.startAnchorId], ["End", current.endAnchorId]];
+ return group("Semantic anchors", endpoints.map(([label, anchorId]) => {
+ const anchor = semantic.anchors.find((item) => item.id === anchorId)!;
+ const describe = (item: typeof anchor) => {
+ const word = semantic.tokens.find((token) => token.id === item.tokenId)?.text;
+ return `${item.kind.replaceAll("-", " ")}${word ? ` · ${word}` : ""}${item.segmentId ? ` · ${item.segmentId}` : ""}`;
+ };
+ const candidates = semantic.anchors.filter((item) => item.frame === anchor.frame).flatMap((item) => {
+ const target: SemanticTarget = "anchorId" in current ? { kind: "moment", anchorId: item.id }
+ : { kind: "selection", startAnchorId: label === "Start" ? item.id : current.startAnchorId,
+ endAnchorId: label === "End" ? item.id : current.endAnchorId };
+ const owner = consumers.find(({ handle }) => semanticGestureSpan(semantic.anchors, handle, target) !== undefined);
+ return owner ? [{ item, target, ...owner }] : [];
+ });
+ if (candidates.length < 2) return property(label!, describe(anchor));
+ const row = document.createElement("label");
+ row.className = "property";
+ const name = document.createElement("span");
+ name.textContent = label!;
+ const control = document.createElement("select");
+ control.className = "parameter-value";
+ control.setAttribute("aria-label", `${label} semantic anchor`);
+ for (const { item } of candidates) {
+ const option = document.createElement("option"); option.value = item.id; option.textContent = describe(item);
+ control.append(option);
+ }
+ control.value = anchorId!;
+ control.addEventListener("change", () => {
+ const choice = candidates.find(({ item }) => item.id === control.value)!;
+ const span = semanticGestureSpan(semantic.anchors, choice.handle, choice.target)!;
+ const temporal = choice.handle.temporal!;
+ control.disabled = true;
+ status.textContent = "Saving"; status.className = "status saving";
+ void applyStudioMutation({ type: "timeline.adjust", revision: snapshot.revision,
+ entityId: choice.clip.id, gesture: choice.handle.gesture,
+ target: temporal.kind === "instant" ? { kind: "instant", frame: span.startFrame, semantic: choice.target }
+ : { kind: "window", ...span, semantic: choice.target },
+ }).then(() => { status.textContent = "Saved"; status.className = "status saved"; })
+ .catch((error: unknown) => {
+ control.value = anchorId!; status.textContent = "Save failed"; status.className = "status error";
+ status.title = error instanceof Error ? error.message : String(error);
+ }).finally(() => { control.disabled = false; });
+ });
+ row.append(name, control);
+ return row;
+ }));
+}
+
function renderSemanticSelectionInspector(snapshot: StudioSnapshot, selectionId: string): void {
const selection = snapshot.semantic?.selections.find((item) => item.id === selectionId);
if (selection === undefined) { inspector.replaceChildren(); return; }
defaultWorkspaceHeading();
- const empty = document.createElement("div");
- empty.className = "inspector-empty";
- empty.textContent = "Adjust on the timeline";
- inspector.replaceChildren(empty);
+ inspector.replaceChildren(semanticAnchorInspector(snapshot, "selection", selectionId));
}
function renderSemanticMomentInspector(snapshot: StudioSnapshot, momentId: string): void {
const moment = snapshot.semantic?.moments.find((item) => item.id === momentId);
if (moment === undefined) { inspector.replaceChildren(); return; }
defaultWorkspaceHeading();
- const empty = document.createElement("div");
- empty.className = "inspector-empty";
- empty.textContent = "Adjust on the timeline";
- inspector.replaceChildren(empty);
+ inspector.replaceChildren(semanticAnchorInspector(snapshot, "moment", momentId));
}
// The word being spoken at the playhead, which is the point of carrying token
diff --git a/packages/studio/src/ui/timeline.ts b/packages/studio/src/ui/timeline.ts
index 3c9a55af..7db4254a 100644
--- a/packages/studio/src/ui/timeline.ts
+++ b/packages/studio/src/ui/timeline.ts
@@ -8,6 +8,7 @@ import { mountMaterialPreview } from "./material-preview.js";
import type { State, Store } from "./selection.js";
import { createHandle } from "./resize.js";
import { createZoom } from "./zoom.js";
+import { chooseSemanticGesture, semanticGestureSpan } from "../temporal-edit.js";
import { applyStudioMutation } from "./writeback.js";
export type Timeline = {
@@ -220,107 +221,17 @@ export function createTimeline(store: Store): Timeline {
readonly clip: StudioSnapshot["tracks"][number]["clips"][number];
readonly handle: StudioEditHandle;
readonly startFrame: number;
- readonly pointerAnchorIndex?: number;
readonly pointerId: number;
readonly node: HTMLElement;
readonly originalLeft: string;
readonly originalWidth: string;
} | undefined;
- const nearestAnchorIndex = (
- frame: number,
- indices: readonly number[],
- preferredIndex?: number,
- ): number | undefined => {
- if (state === undefined) return undefined;
- const anchors = state.snapshot.semantic?.anchors ?? [];
- const preferredKind = preferredIndex === undefined ? undefined : anchors[preferredIndex]?.kind;
- return [...indices].sort((left, right) => {
- const leftAnchor = anchors[left]!;
- const rightAnchor = anchors[right]!;
- return Math.abs(leftAnchor.frame - frame) - Math.abs(rightAnchor.frame - frame)
- || Number(leftAnchor.kind !== preferredKind) - Number(rightAnchor.kind !== preferredKind)
- || Math.abs(left - (preferredIndex ?? left)) - Math.abs(right - (preferredIndex ?? right))
- || left - right;
- })[0];
- };
-
- const semanticTarget = (
- edit: NonNullable<typeof activeEdit>,
- nextFrame: number,
- ): { readonly kind: "selection"; readonly startAnchorId: string; readonly endAnchorId: string }
- | { readonly kind: "moment"; readonly anchorId: string }
- | undefined => {
- if (state === undefined || edit.handle.semantic === undefined) return undefined;
- const semantic = edit.handle.semantic;
- const anchors = state.snapshot.semantic?.anchors ?? [];
- if (semantic.kind === "moment") {
- const currentIndex = anchors.findIndex((anchor) => anchor.id === semantic.anchorId);
- const anchorIndex = nearestAnchorIndex(
- nextFrame,
- anchors.map((_, index) => index),
- currentIndex < 0 ? undefined : currentIndex,
- );
- return anchorIndex === undefined ? undefined : { kind: "moment", anchorId: anchors[anchorIndex]!.id };
- }
- const startIndex = anchors.findIndex((anchor) => anchor.id === semantic.startAnchorId);
- const endIndex = anchors.findIndex((anchor) => anchor.id === semantic.endAnchorId);
- if (startIndex < 0 || endIndex < 0 || startIndex >= endIndex) return undefined;
- let nextStart = startIndex;
- let nextEnd = endIndex;
- if (edit.handle.gesture === "trim-start") {
- const allowed = anchors.flatMap((anchor, index) =>
- index < endIndex && anchor.frame < anchors[endIndex]!.frame ? [index] : []);
- nextStart = nearestAnchorIndex(nextFrame, allowed, startIndex) ?? startIndex;
- } else if (edit.handle.gesture === "trim-end") {
- const allowed = anchors.flatMap((anchor, index) =>
- index > startIndex && anchor.frame > anchors[startIndex]!.frame ? [index] : []);
- nextEnd = nearestAnchorIndex(nextFrame, allowed, endIndex) ?? endIndex;
- } else if (edit.handle.gesture === "move") {
- const instantBoundary = edit.handle.temporal?.kind === "instant"
- && edit.handle.temporal.authority.kind === "semantic"
- && edit.handle.temporal.authority.source.kind === "selection"
- ? edit.handle.temporal.authority.boundary
- : undefined;
- if (instantBoundary === "start") {
- const allowed = anchors.flatMap((anchor, index) =>
- index < endIndex && anchor.frame < anchors[endIndex]!.frame ? [index] : []);
- nextStart = nearestAnchorIndex(nextFrame, allowed, startIndex) ?? startIndex;
- return { kind: "selection", startAnchorId: anchors[nextStart]!.id, endAnchorId: anchors[nextEnd]!.id };
- }
- if (instantBoundary === "end") {
- const allowed = anchors.flatMap((anchor, index) =>
- index > startIndex && anchor.frame > anchors[startIndex]!.frame ? [index] : []);
- nextEnd = nearestAnchorIndex(nextFrame, allowed, endIndex) ?? endIndex;
- return { kind: "selection", startAnchorId: anchors[nextStart]!.id, endAnchorId: anchors[nextEnd]!.id };
- }
- const pointerIndex = edit.pointerAnchorIndex ?? startIndex;
- const deltas = anchors.flatMap((_, index) => {
- const delta = index - pointerIndex;
- const movedStart = startIndex + delta;
- const movedEnd = endIndex + delta;
- return movedStart >= 0 && movedEnd < anchors.length
- && anchors[movedStart]!.frame < anchors[movedEnd]!.frame
- ? [delta]
- : [];
- });
- const targetPointer = nearestAnchorIndex(
- nextFrame,
- deltas.map((delta) => pointerIndex + delta),
- pointerIndex,
- );
- const delta = targetPointer === undefined ? 0 : targetPointer - pointerIndex;
- nextStart += delta;
- nextEnd += delta;
- } else {
- return undefined;
- }
- return {
- kind: "selection",
- startAnchorId: anchors[nextStart]!.id,
- endAnchorId: anchors[nextEnd]!.id,
- };
- };
+ const semanticTarget = (edit: NonNullable<typeof activeEdit>, nextFrame: number) =>
+ state === undefined ? undefined : chooseSemanticGesture({
+ anchors: state.snapshot.semantic?.anchors ?? [], handle: edit.handle,
+ pointerStart: edit.startFrame, pointerNow: nextFrame, frameCount: state.snapshot.space.frameCount,
+ });
const absoluteWindowTarget = (
edit: NonNullable<typeof activeEdit>,
@@ -353,40 +264,8 @@ export function createTimeline(store: Store): Timeline {
): { readonly startFrame: number; readonly endFrameExclusive: number } | undefined => {
if (state === undefined) return undefined;
const target = semanticTarget(edit, nextFrame);
- if (target?.kind === "selection" && edit.handle.semantic?.kind === "selection") {
- const current = state.snapshot.semantic?.selections.find((selection) => selection.id === edit.handle.semantic!.id);
- const nextStart = state.snapshot.semantic?.anchors.find((anchor) => anchor.id === target.startAnchorId)?.frame;
- const nextEnd = state.snapshot.semantic?.anchors.find((anchor) => anchor.id === target.endAnchorId)?.frame;
- if (current === undefined || nextStart === undefined || nextEnd === undefined) return undefined;
- const instantBoundary = edit.handle.temporal?.kind === "instant"
- && edit.handle.temporal.authority.kind === "semantic"
- && edit.handle.temporal.authority.source.kind === "selection"
- ? edit.handle.temporal.authority.boundary
- : undefined;
- if (instantBoundary === "start" || instantBoundary === "end") {
- const frame = instantBoundary === "start" ? nextStart : nextEnd;
- return { startFrame: frame, endFrameExclusive: frame + 1 };
- }
- return {
- startFrame: nextStart + edit.clip.startFrame - current.startFrame,
- endFrameExclusive: nextEnd + edit.clip.endFrameExclusive - current.endFrameExclusive,
- };
- }
- if (target?.kind === "moment" && edit.handle.semantic?.kind === "moment") {
- const current = state.snapshot.semantic?.moments.find((moment) => moment.id === edit.handle.semantic!.id);
- const next = state.snapshot.semantic?.anchors.find((anchor) => anchor.id === target.anchorId)?.frame;
- if (current === undefined || next === undefined) return undefined;
- const delta = next - current.frame;
- if (edit.handle.gesture === "trim-start") {
- return { startFrame: next, endFrameExclusive: edit.clip.endFrameExclusive };
- }
- if (edit.handle.gesture === "trim-end") {
- return { startFrame: edit.clip.startFrame, endFrameExclusive: next };
- }
- return edit.handle.moveEffect === "move-start"
- ? { startFrame: edit.clip.startFrame + delta, endFrameExclusive: edit.clip.endFrameExclusive }
- : { startFrame: edit.clip.startFrame + delta, endFrameExclusive: edit.clip.endFrameExclusive + delta };
- }
+ if (target !== undefined) return semanticGestureSpan(state.snapshot.semantic?.anchors ?? [], edit.handle, target);
+ if (edit.handle.semantic !== undefined) return undefined;
return edit.handle.temporal === undefined ? undefined : absoluteWindowTarget(edit, nextFrame);
};
lanes.addEventListener("pointerdown", (event) => {
@@ -860,17 +739,10 @@ export function createTimeline(store: Store): Timeline {
const pointerFrame = handle.coordinate === "semantic-anchor"
? rawFrameAt(event.clientX)
: frameAt(event.clientX);
- const pointerAnchorIndex = handle.semantic !== undefined
- ? nearestAnchorIndex(
- pointerFrame,
- state?.snapshot.semantic?.anchors.map((_, index) => index) ?? [],
- )
- : undefined;
activeEdit = {
clip,
handle,
startFrame: pointerFrame,
- ...(pointerAnchorIndex === undefined ? {} : { pointerAnchorIndex }),
pointerId: event.pointerId,
node,
originalLeft: node.style.left,
diff --git a/packages/studio/test/parameter-values.test.ts b/packages/studio/test/parameter-values.test.ts
new file mode 100644
index 00000000..1d57606c
--- /dev/null
+++ b/packages/studio/test/parameter-values.test.ts
@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { StudioInspectorField } from "@hypit/studio-adapter";
+import { parameterAuthorValue, parameterNumber, parameterOption, serializeParameterValue, validateParameterValue } from "../src/parameter-values.js";
+
+const field = (overrides: Partial<StudioInspectorField>): StudioInspectorField => ({
+ id: "width", binding: "frame.width", label: "Width", domain: "where", section: { id: "size", label: "Size" },
+ control: "number", value: "78%", language: "svml", source: { path: "main.svml", range: { start: 0, end: 3 }, preimage: "78%" },
+ number: { suffixes: ["%", "px"] }, ...overrides,
+});
+
+test("numeric editing separates units and restores the authored unit without converting it", () => {
+ for (const [value, suffix] of [["78%", "%"], ["78px", "px"]]) {
+ const held = field({ value: value! });
+ assert.deepEqual(parameterNumber(held.value, held.number), { value: 78, suffix });
+ assert.equal(parameterAuthorValue(held, 42.5), `42.5${suffix}`);
+ assert.throws(() => parameterAuthorValue(held, "42.5%"), /finite number/u);
+ }
+ assert.throws(() => parameterNumber("auto", { suffixes: ["%", "px"] }), /unit/u);
+ assert.throws(() => parameterNumber(""), /numeric/u);
+ const seconds = field({ value: "0.25s", number: { suffixes: ["ms", "s", "f"] } });
+ assert.equal(parameterAuthorValue(seconds, .5), "0.5s");
+});
+
+test("percentage display and schema validation apply on opposite sides of the translation", () => {
+ const opacity = field({ value: .78, language: "svs", unit: "%", number: { scale: 100, minimum: 0, maximum: 100 },
+ schema: { kind: "number", minimum: 0, maximum: 1 } });
+ assert.equal(parameterNumber(opacity.value, opacity.number).value, 78);
+ assert.equal(parameterNumber(.55, opacity.number).value, 55);
+ assert.equal(parameterAuthorValue(opacity, 55), .55);
+ const value = parameterAuthorValue(opacity, 42);
+ assert.equal(value, .42);
+ validateParameterValue(value, opacity.schema!, "Opacity");
+ assert.equal(serializeParameterValue(value, "svs"), "0.42");
+ assert.throws(() => parameterAuthorValue(opacity, 101), /at most/u);
+ assert.throws(() => parameterAuthorValue(opacity, NaN), /finite/u);
+});
+
+test("rich options preserve values independently of labels and visual hints", () => {
+ assert.deepEqual(parameterOption("loop"), { value: "loop", label: "loop" });
+ const font = { value: "editorial", label: "Editorial Serif", description: "Project headline face", preview: { kind: "font", family: "Project Serif" } } as const;
+ assert.equal(parameterOption(font).value, "editorial");
+ assert.equal(parameterOption({ value: 700, label: "Bold" }).value, 700);
+});
+
+test("SVML parameter text escapes attribute delimiters while SVS keeps its own codec", () => {
+ const text = 'Say "hello" & <look> at Bob\'s';
+ assert.equal(serializeParameterValue(text, "svml"), "Say &quot;hello&quot; &amp; &lt;look&gt; at Bob&apos;s");
+ assert.equal(serializeParameterValue(text, "svs"), JSON.stringify(text));
+});
diff --git a/packages/studio/test/parameters.test.ts b/packages/studio/test/parameters.test.ts
index 658a3496..f9d8051c 100644
--- a/packages/studio/test/parameters.test.ts
+++ b/packages/studio/test/parameters.test.ts
@@ -133,7 +133,6 @@ test("at/for and until/for derive complementary semantic and duration inverses",
}, withMoment);
assert.deepEqual(atFor.map((handle) => [handle.gesture, handle.semantic?.kind, handle.sources?.map((source) => source.role)]), [
["move", "moment", undefined],
- ["trim-start", "moment", ["duration"]],
["trim-end", undefined, ["duration"]],
]);
@@ -143,7 +142,6 @@ test("at/for and until/for derive complementary semantic and duration inverses",
assert.deepEqual(untilFor.map((handle) => [handle.gesture, handle.semantic?.kind, handle.sources?.map((source) => source.role)]), [
["move", "moment", undefined],
["trim-start", undefined, ["duration"]],
- ["trim-end", "moment", ["duration"]],
]);
});
@@ -196,6 +194,29 @@ test("absolute Window edits work without a semantic lane and use the Companion's
]);
});
+test("independent reference endpoints expose local edits without claiming their Script identities", () => {
+ const endpoints = (["start", "end"] as const).map((name, index) => ({
+ kind: "instant" as const, expression: index === 0 ? "selection.start" : "moment.cue",
+ reference: index === 0 ? "selection.start" as const : "moment.cue" as const,
+ frame: index === 0 ? 2 : 20,
+ source: { ...temporalIdentity, kind: index === 0 ? "selection" as const : "moment" as const, id: index === 0 ? "claim" : "beat" },
+ authority: { kind: "parameter" as const, binding: name, relation: "direct" as const },
+ }));
+ const bindings = (["start", "end"] as const).map((name, index) => ({
+ id: name, binding: name, name, value: endpoints[index]!.expression,
+ language: "svml" as const, writable: true,
+ source: { endpoint: `main::${name}`, path: "main.svml", range: { start: index * 20, end: index * 20 + 10 }, preimage: endpoints[index]!.expression },
+ }));
+ const handles = resolveTimelineEditHandles(bindings, { projection: {
+ kind: "window", start: endpoints[0]!, end: endpoints[1]!, startFrame: 2, endFrameExclusive: 20,
+ }, phases: [] }, semantic);
+ assert.deepEqual(handles.map(({ gesture, enabled, semantic, sources }) => ({ gesture, enabled, semantic, roles: sources?.map(source => source.role) })), [
+ { gesture: "move", enabled: true, semantic: undefined, roles: ["start", "end"] },
+ { gesture: "trim-start", enabled: true, semantic: undefined, roles: ["start"] },
+ { gesture: "trim-end", enabled: true, semantic: undefined, roles: ["end"] },
+ ]);
+});
+
test("parameter Source paths stay relative to the author workspace", () => {
const text = "start=\"1f\"";
const parameters = sourceBindingsForDraft({
@@ -225,6 +246,37 @@ test("parameter Source paths stay relative to the author workspace", () => {
assert.equal(parameters[0]!.source.preimage, "1f");
});
+test("nested declared references reach the font attribute, not the referring Style", () => {
+ const text = '<Font family="montserrat"/>';
+ const base = (id: string): StudioPlacement => ({
+ id, sourcePath: "main.svml", tag: "Test", module: { name: "example", version: "1" },
+ surface: "test", range: { start: 0, end: text.length }, records: [], values: [],
+ outputs: [`main::record::${id}`], outputPorts: [], children: [], attributes: {},
+ attributeValueRanges: {}, referenceAttributes: {}, referenceTypes: {}, references: [],
+ });
+ const track: StudioPlacement = { ...base("track"),
+ referenceAttributes: { style: "shared-style" },
+ resolvedReferenceAttributes: { style: "main::record::style" },
+ };
+ const style: StudioPlacement = { ...base("style"), referenceAttributes: { font: "shared-font" },
+ resolvedReferenceAttributes: { font: "main::record::font" },
+ };
+ const font: StudioPlacement = { ...base("font"), attributes: { family: "montserrat" },
+ attributeValueRanges: { family: { start: 14, end: 24 } },
+ };
+ const parameters = sourceBindingsForDraft({
+ root: "/workspace", files: [{ path: "main.svml", text, language: "svml" }],
+ placement: track, placements: [track, style, font],
+ draft: { id: "track:entity", authoredId: "track", display: { title: "track", layers: [] },
+ startFrame: 0, endFrameExclusive: 10, stackOrder: 0, elementRange: track.range },
+ declarations: [{ name: "style", referenced: [{ name: "font", referenced: [{ name: "family", writable: true }] }] }],
+ });
+ const family = parameters.find(parameter => parameter.binding === "style.font.family");
+ assert.equal(family?.value, "montserrat");
+ assert.equal(family?.source.preimage, "montserrat");
+ assert.equal(family?.writable, true);
+});
+
test("a derived entity follows its actual Style and Companion-owned Recipe presentation", () => {
const main = "<caption-fine:Track id=\"captions\" program={caption-program}/>";
const sheet = `<sheet version="1">
diff --git a/packages/studio/test/semantic-gesture.test.ts b/packages/studio/test/semantic-gesture.test.ts
new file mode 100644
index 00000000..bed257dd
--- /dev/null
+++ b/packages/studio/test/semantic-gesture.test.ts
@@ -0,0 +1,97 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { StudioEditHandle, StudioSemanticAnchor, StudioTemporalInstantProjection } from "@hypit/studio-adapter";
+import { adjustScriptSelection, parseScript } from "@hypit/script";
+import { projectProgramInstant } from "@hypit/temporal";
+import { parseTemporalInstant } from "@hypit/temporal-markup";
+import { chooseSemanticGesture, formatTemporalPointEdit, semanticGestureSpan } from "../src/temporal-edit.js";
+
+const source = '<one><HOST>@proof One two @/proof three.</one>';
+const narrative = parseScript("gesture", source);
+// Duplicate word/Segment boundaries count as one stop, not additional movement steps.
+const frames = [0, 0, 0, 5, 10, 20, 40, 55, 55, 55];
+const anchors: readonly StudioSemanticAnchor[] = narrative.semanticIndex.anchors.map((anchor, index) => ({ ...anchor, frame: frames[index]! }));
+const selection = narrative.selections[0]!;
+const temporalSource = { kind: "selection", id: "proof", narrativeId: "story", spaceId: "film" } as const;
+const endpoint = (boundary: "start" | "end", frame: number): StudioTemporalInstantProjection => ({
+ kind: "instant", expression: `selection.${boundary}`, reference: `selection.${boundary}`, source: temporalSource, frame,
+ authority: { kind: "semantic", source: temporalSource, boundary },
+});
+const handle: StudioEditHandle = {
+ id: "move", operation: "timeline.adjust", gesture: "move", enabled: true,
+ semantic: { kind: "selection", id: "proof", narrativeId: "story", startAnchorId: selection.startAnchorId, endAnchorId: selection.endAnchorId },
+ temporal: { kind: "window", start: endpoint("start", 0), end: endpoint("end", 20), startFrame: 0, endFrameExclusive: 20 },
+};
+const choose = (h: StudioEditHandle, from: number, to: number, list = anchors) => chooseSemanticGesture({
+ anchors: list, handle: h, pointerStart: from, pointerNow: to, frameCount: 100,
+});
+
+test("Selection move advances both ends one stop, changes duration, and writes back through Script", () => {
+ const target = choose(handle, 0, 5)!;
+ assert.equal(target.kind, "selection");
+ if (target.kind !== "selection") return;
+ assert.deepEqual(semanticGestureSpan(anchors, handle, target), { startFrame: 5, endFrameExclusive: 40 });
+ const rewritten = adjustScriptSelection({ sourceName: "gesture", source, parsed: narrative, adjustment: { id: "proof", ...target } });
+ const next = parseScript("gesture", rewritten).selections[0]!;
+ assert.equal(next.startAnchorId, target.startAnchorId);
+ assert.equal(next.endAnchorId, target.endAnchorId);
+ const moved: StudioEditHandle = { ...handle, semantic: { ...handle.semantic!, ...target }, temporal: {
+ kind: "window", start: endpoint("start", 5), end: endpoint("end", 40), startFrame: 5, endFrameExclusive: 40,
+ } };
+ const back = choose(moved, 5, 0)!;
+ assert.deepEqual(semanticGestureSpan(anchors, moved, back), { startFrame: 0, endFrameExclusive: 20 });
+});
+
+test("coincident anchors preserve the current identity without preferring starts to ends", () => {
+ assert.deepEqual(choose(handle, 0, 0), { kind: "selection", startAnchorId: selection.startAnchorId, endAnchorId: selection.endAnchorId });
+ const point: StudioEditHandle = { ...handle, temporal: endpoint("end", 20) };
+ assert.equal(choose(point, 20, 40)?.kind, "selection");
+});
+
+test("a directly selected boundary remains editable even when the raw range reverses in time", () => {
+ const overlapping = anchors.map((anchor) => anchor.id === selection.startAnchorId ? { ...anchor, frame: 30 } : anchor);
+ const point: StudioEditHandle = { ...handle, temporal: endpoint("start", 30) };
+ const unchanged = { kind: "selection", startAnchorId: selection.startAnchorId, endAnchorId: selection.endAnchorId } as const;
+ assert.deepEqual(semanticGestureSpan(overlapping, point, unchanged), { startFrame: 30, endFrameExclusive: 31 });
+ assert.equal(semanticGestureSpan(overlapping, handle, unchanged), undefined);
+ assert.ok(choose(point, 30, 40, overlapping));
+});
+
+test("dragging a bound Moment keeps an event-and-duration Window intact", () => {
+ const momentSource = { ...temporalSource, kind: "moment", id: "beat" } as const;
+ const moment: StudioTemporalInstantProjection = { kind: "instant", frame: 20, expression: "moment.cue", reference: "moment.cue", source: momentSource,
+ authority: { kind: "semantic", source: momentSource, boundary: "cue" } };
+ const timed: StudioEditHandle = { ...handle, semantic: { kind: "moment", id: "beat", narrativeId: "story", anchorId: selection.endAnchorId }, temporal: {
+ kind: "window", start: moment, end: { ...moment, frame: 28, authority: { kind: "parameter", binding: "for", relation: "after-start" } },
+ startFrame: 20, endFrameExclusive: 28,
+ } };
+ const target = choose(timed, 20, 40)!;
+ assert.deepEqual(semanticGestureSpan(anchors, timed, target), { startFrame: 40, endFrameExclusive: 48 });
+});
+
+
+test("offset edits cross zero without losing the explicit editable parameter", () => {
+ assert.equal(formatTemporalPointEdit("moment.cue", 12, 10), "moment.cue+2f");
+ assert.equal(formatTemporalPointEdit("moment.cue", 10, 10), "moment.cue+0f");
+ assert.equal(formatTemporalPointEdit("moment.cue", 8, 10), "moment.cue-2f");
+ assert.equal(formatTemporalPointEdit("absolute", 8), "8f");
+});
+
+test("clock expressions retain units until edited and edited values reproject to the exact frame", () => {
+ for (const frameRate of [{ numerator: 30, denominator: 1 }, { numerator: 60, denominator: 1 }, { numerator: 30000, denominator: 1001 }]) {
+ const space = { id: "clock", durationSec: 300 * frameRate.denominator / frameRate.numerator, frameRate };
+ const locate = (value: string) => projectProgramInstant({
+ itemId: "point", subjectId: "point", space,
+ projection: parseTemporalInstant(value, "point"), authority: { kind: "parameter", binding: "instant", relation: "direct" },
+ }).frame;
+ assert.equal(locate("2s"), Math.round(2 * frameRate.numerator / frameRate.denominator));
+ assert.equal(locate("60f"), 60);
+ const original = locate("1.017s");
+ for (const delta of [3, -2, 0]) {
+ const desired = original + delta;
+ assert.equal(locate(formatTemporalPointEdit("absolute", desired)), desired);
+ const base = locate("program.end");
+ assert.equal(locate(formatTemporalPointEdit("program.end", desired, base)), desired);
+ }
+ }
+});
diff --git a/packages/temporal-markup/EDITING.md b/packages/temporal-markup/EDITING.md
new file mode 100644
index 00000000..f3409586
--- /dev/null
+++ b/packages/temporal-markup/EDITING.md
@@ -0,0 +1,183 @@
+# Author-directed time editing
+
+The shared temporal author forms declare what Studio can edit. The tables below describe their
+implemented behavior; a component's Companion also supplies the actual Source bindings.
+The runtime projection types remain `@1`.
+
+## Relationships, expressions, and resolved time
+
+Selection and Moment name relationships in a Narrative. A Selection names two anchors; a Moment
+names one. Neither carries a duration measured in seconds. Segment and Program boundaries retain
+their structural meaning alongside word boundaries.
+
+A temporal expression describes how to obtain time from those relationships or from a clock.
+Projection resolves that description in a ProgramSpace. Its products are TemporalInstant and
+TemporalWindow, which a component consumes to implement its own schedule and appearance.
+
+In temporal author attributes, `{story.moment.reveal}` is a direct typed reference. Quoted values
+such as `"2s"` and `"moment.cue + 2f"` are clock descriptions. Quotation marks do not themselves
+produce an Instant or Window, and braces elsewhere in SVML can reference any public value type.
+Both semantic references and clock descriptions reach consumers through temporal projection.
+The consumer's role determines whether one Instant or a Window is needed.
+
+The editing rule is: **edit the relationship or parameter the author exposed, preserving the
+relationship they chose to depend on.** Knowing where a result came from does not by itself grant
+an inverse that changes that source.
+
+## Direct bindings
+
+| Author form | Move | Leading edge | Trailing edge |
+| --- | --- | --- | --- |
+| `during={story.selection.proof}` | Move both Selection anchors by the same number of semantic stops; duration may change. | Change its start anchor. | Change its end anchor. |
+| `at={story.moment.reveal}` for an Instant | Change the Moment anchor. | Not applicable. | Not applicable. |
+| `at={story.selection.proof} boundary="start"` for an Instant | Change only the Selection start anchor. | Not applicable. | Not applicable. |
+| `at={story.selection.proof} boundary="end"` for an Instant | Change only the Selection end anchor. | Not applicable. | Not applicable. |
+| `during={story.segment.opening}` or `during="program"` | Follow the structural span; no timeline write. | No timeline write. | No timeline write. |
+| A directly selected Segment boundary | Follow that structural boundary; no timeline write. | Not applicable. | Not applicable. |
+
+A shared Selection or Moment is edited once in Script. All its consumers follow after compilation.
+An item's placement in a track does not make its own private copy of that relationship.
+
+Word starts, word ends, Segment starts, and Segment ends are equally eligible semantic anchors.
+Selection starts do not inherently prefer word starts; Selection ends do not inherently prefer
+word ends. Endpoints can include pauses by referring to the appropriate neighboring anchor.
+
+## An event and a duration
+
+These forms expose two independent decisions: an event or clock position, and a duration.
+
+| Author form | Move | Leading edge | Trailing edge |
+| --- | --- | --- | --- |
+| `at={story.moment.reveal} for="8f"` | Change the Moment; keep `for`. | No handle. | Change `for`; keep the Moment. |
+| `until={story.moment.reveal} for="8f"` | Change the Moment; keep `for`. | Change `for`; keep the Moment. | No handle. |
+| `at="2s" for="8f"` | Change `at`; keep `for`. | No handle. | Change `for`; keep `at`. |
+| `until="2s" for="8f"` | Change `until`; keep `for`. | Change `for`; keep `until`. | No handle. |
+
+Moving an event-and-duration window preserves duration. Moving a direct Selection window preserves
+semantic step displacement instead. These are different author decisions, so they have different
+behavior even when their current rectangles look identical.
+
+The unavailable edge does not secretly edit both the event and the duration. Duration editing is
+frame-based; semantic event editing selects an anchor. There is no `at` plus `until` Window form:
+current forms are `during`, `at/for`, `until/for`, and `start/end`.
+
+## Clock positions and explicit offsets
+
+A literal Instant such as `at="2s"` exposes one numeric time and can move by rewriting that value.
+A reference expression exposes a local offset while retaining its referenced event:
+
+```svml
+moment={story.moment.reveal}
+instant="moment.cue + 2f"
+```
+
+Moving this Instant changes the signed offset only. It does not relocate the Moment in Script.
+The same rule applies to an explicit offset from a selected boundary or a Program boundary.
+The expression's reference remains unchanged through the write.
+
+A bare reference expression such as `instant="moment.cue"` has an implicit zero offset. Moving it
+writes an offset such as `moment.cue+3f`; it leaves the Moment in Script unchanged. The direct
+binding `at={...}` is the form that edits the Moment itself.
+
+Bare references and explicit `+0f` have the same editing behavior. Writeback uses an explicit frame
+offset, including at zero. Positive, zero, and negative offsets belong to the same editing operation,
+subject to the resulting projection being usable.
+
+The existing syntax uses `instant` for expressions and a separate typed `moment`, `selection`, or
+`segment` attribute to bind their source. This design does not add an implicit name resolver or
+put arithmetic inside `{...}`. Unifying surface attribute spellings is a separate usability choice,
+not a prerequisite for establishing these edit semantics.
+
+## Independently authored endpoints
+
+`start="..." end="..."` expresses a deliberately assembled Window. Its expressions may use different
+sources, boundaries, absolute times, and offsets. This form remains available for production,
+including pure motion graphics and windows extending around a spoken passage.
+
+Each endpoint is edited exactly like an Instant expression: a literal changes its absolute time;
+a reference changes its local offset. A leading trim changes `start`, a trailing trim changes `end`,
+and a whole-window move shifts both endpoints by the same frame delta. Each expression retains its
+own reference, even when the endpoints depend on different sources. The referenced Script markers
+remain unchanged. Companion bindings identify the two writable source parameters.
+
+## Seconds and frames
+
+Seconds and milliseconds describe clock duration; frames describe steps at the ProgramSpace's
+frame rate. `2s` remains two seconds when the rate changes, whereas `60f` spans two seconds at 30fps
+and one second at 60fps. Parsing retains that authored unit. Projection uses exact rational arithmetic
+and rounds the resulting position to the nearest frame boundary, with half-frame ties rounding later.
+
+Timeline gestures operate on whole frames in the current ProgramSpace. A changed absolute value is
+written in frames, and a changed reference expression receives a frame offset. Unedited expressions
+retain their spelling and units. This makes a drag's result exact at the current frame rate without
+silently converting all authored clock durations into frame counts.
+
+## Semantic stops and coincident anchors
+
+Script order, anchor identity, and projected frame position are separate data:
+
+- Script order determines which inline Selection an author surface can express.
+- Projected frame position determines where an event appears in the current performance.
+- Anchor identity determines which relationship survives later changes to that performance.
+
+Build the gesture's semantic stops from distinct projected frame positions in chronological order.
+Several anchors at one frame occupy one stop but retain their individual identities. A direct
+Selection move advances both endpoints by the same signed number of stops. It does not shift a raw
+anchor-array index, assume one stop is one word, or preserve a duration measured in frames.
+
+Ties first retain the current anchor where it is still a candidate, then prefer its kind, then use
+a stable declared order. This is a default choice among coincident candidates, not a hierarchy of
+valid anchors. Selecting a semantic marker shows its exact anchors in the Inspector. Where declared
+handles allow it, a choice lists the other anchors at the same frame; horizontal mouse position alone
+cannot distinguish them. That explicit choice uses the same Script adjustment operation as dragging.
+
+Segment overlap or gaps can change temporal order without changing Script order. Stop construction
+must not assume contiguous Segments. The current SemanticTrack implementation still concatenates
+Take durations; introducing explicit Take placement is separate work.
+
+## Selection, projection, and consumption
+
+A Selection that is forward in Script may locate to equal or reversed frame endpoints. This does
+not alone establish whether every use of that Selection is invalid. A consumer may use only its
+start, or an expression may add offsets before composing a Window.
+
+Script validates the relationship it can express. Temporal projection validates the resulting
+Instant or Window in its ProgramSpace. Components validate their own use of those results.
+Studio offers only gestures with a declared inverse and candidate targets that preserve the
+edited object's usable projection. It does not add a global positive-duration rule to Selection.
+
+Both endpoints of a range adjustment are written in one operation. Recompilation remains the check
+for effects on other consumers of the shared relationship. An unsuccessful publication leaves the
+previous source and displayed state in place through the existing source transaction; this does not
+introduce a Build recovery workflow or a second mutable source of truth.
+
+A hidden or invalid initial object does not need an automatic repair interface. Conversely, a valid
+editable object must not disappear because the editor committed a target its own projection cannot
+represent. The relevant closure is over meaningful relationships and supported operations, not every
+possible raw spelling of the document.
+
+## Implementation ownership
+
+The existing protocol already distinguishes `TemporalSource` from `TemporalInstantAuthority`.
+Preserve this separation. A source says what time depends on; authority identifies an intentional
+write target. The `fixed` case means no temporal gesture writes that endpoint, not that all author
+parameter editing is forbidden.
+
+- `@hypit/script` owns tokenization, anchor identities, legal marker sites, and structural writeback.
+ It normalizes equivalent marker whitespace, retains punctuation and attributes, writes coincident
+ markers together, and preserves all unrelated relationships and caption information.
+- `@hypit/temporal-markup` owns the interpretation of each time form and declares its write targets.
+ Direct semantic references expose semantic targets; quoted time expressions expose parameter
+ targets, including implicit zero offsets and independent endpoints. Structural bindings retain
+ their structural boundaries without a timeline write target.
+- `@hypit/temporal` resolves time and validates its results. It does not infer a user editing choice
+ from invertibility or know Studio's UI.
+- Companion/Studio translates those declared relationships into the finite operations above.
+ Existing `after-start` and `before-end` duration relationships already distinguish event-and-duration
+ windows. Explicit source bindings remain the write allowlist. Component names and media types
+ do not decide which operation is available.
+
+Script tests exercise repeated marker moves and return trips across English, Chinese, Dual Text,
+punctuation, token attributes, and empty Segments. Temporal Markup tests check author authority;
+Studio tests check handles, semantic-stop movement, projected validity, and offset writes through zero.
+The same semantic gesture projection is used for the timeline preview and server-side validation.
diff --git a/packages/temporal-markup/README.md b/packages/temporal-markup/README.md
index 68884cb5..f2b586b5 100644
--- a/packages/temporal-markup/README.md
+++ b/packages/temporal-markup/README.md
@@ -9,6 +9,10 @@ The package exports `createTemporalWindowProjection`, `createTemporalInstantProj
`resolveTemporalContext`, `createTemporalSpace`, attribute vocabulary, and the exact duration/instant parsers. These are helpers for component
Surfaces, not standalone author tags or a new Track.
+The editing behavior is specified in [Author-directed time editing](EDITING.md).
+It separates direct bindings, durations, and explicit offsets from derived results, with a precise
+write target for each supported gesture.
+
## Time context
A Track Surface can accept `semantic={speech.semantic}` or `space={animation}`. Resolve that choice
diff --git a/packages/temporal-markup/test/temporal-markup.test.ts b/packages/temporal-markup/test/temporal-markup.test.ts
index 16795d0e..195c168f 100644
--- a/packages/temporal-markup/test/temporal-markup.test.ts
+++ b/packages/temporal-markup/test/temporal-markup.test.ts
@@ -90,3 +90,14 @@ test("authored at/for projects on a declared clock while Script events keep thei
const context = resolveTemporalContext({ element: element({ space: reference("animation") }), resolveReference: path => path === "animation" ? space : undefined });
assert.deepEqual(context, { space });
});
+
+
+test("bare references and explicit offsets expose the same local parameter edit", () => {
+ for (const instant of ["moment.cue", "moment.cue + 0f", "moment.cue - 2f", "20f"]) {
+ const projection = createTemporalInstantProjection({
+ id: "event", element: element({ instant: instant!, ...(instant!.startsWith("moment") ? { moment: reference("moment") } : {}) }),
+ semantic, resolveReference,
+ });
+ assert.deepEqual(specs(projection)[0]!.authority, { kind: "parameter", binding: "instant", relation: "direct" });
+ }
+});
diff --git a/packages/typography-track-studio/package.json b/packages/typography-track-studio/package.json
index cdaf9b16..c3ae5dd0 100644
--- a/packages/typography-track-studio/package.json
+++ b/packages/typography-track-studio/package.json
@@ -4,11 +4,16 @@
"license": "SEE LICENSE IN LICENSE",
"private": true,
"type": "module",
- "exports": { ".": "./src/index.ts" },
- "hypit": { "activation": "./src/activation.ts" },
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "hypit": {
+ "activation": "./src/activation.ts"
+ },
"dependencies": {
"@hypit/composition": "workspace:*",
"@hypit/studio-adapter": "workspace:*",
- "@hypit/typography-track": "workspace:*"
+ "@hypit/typography-track": "workspace:*",
+ "@hypit/fonts-open": "workspace:*"
}
}
diff --git a/packages/typography-track-studio/src/index.ts b/packages/typography-track-studio/src/index.ts
index 20f15907..96cb9f67 100644
--- a/packages/typography-track-studio/src/index.ts
+++ b/packages/typography-track-studio/src/index.ts
@@ -1,9 +1,12 @@
+import { openFontStudioFields } from "@hypit/fonts-open/studio";
import { typographyTrackMarkupSurfaces, typographyTrackModuleRef, typographyTrackTypes } from "@hypit/typography-track";
import type { TypographyTrackProgram } from "@hypit/typography-track";
import { compositionTypes } from "@hypit/composition";
import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration } from "@hypit/studio-adapter";
import { childEntities, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource, textLayer } from "@hypit/studio-adapter";
+const fontInspector = openFontStudioFields("style");
+
const typographyProperties = (typographyTrackMarkupSurfaces
.find((surface) => surface.name === "style")?.vocabulary.attributes
.find((attribute) => attribute.name === "recipe")?.recipe ?? []);
@@ -105,11 +108,12 @@ export const typographyTrackStudioTrackCompanions: readonly StudioTrackCompanion
{ name: "content" },
{
name: "style",
+ referenced: [fontInspector.binding],
recipe: { through: ["recipe"], bindings: typographyProperties.map(({ name }) => ({ name })) },
},
{ name: "motion" },
],
- inspector: typographyInspector,
+ inspector: [...fontInspector.fields, ...typographyInspector],
requiredValues: ["program"], project: projectTypography,
lane: { heightPx: 48 },
},
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5087ec67..ee03080d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -594,6 +594,9 @@ importers:
'@hypit/composition':
specifier: workspace:*
version: link:../composition
+ '@hypit/fonts-open':
+ specifier: workspace:*
+ version: link:../fonts-open
'@hypit/narrative':
specifier: workspace:*
version: link:../narrative
@@ -1081,6 +1084,10 @@ importers:
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
+ devDependencies:
+ '@hypit/studio-adapter':
+ specifier: workspace:*
+ version: link:../studio-adapter
optionalDependencies:
'@fontsource-variable/archivo':
specifier: 5.3.0
@@ -2340,6 +2347,9 @@ importers:
'@hypit/composition':
specifier: workspace:*
version: link:../composition
+ '@hypit/fonts-open':
+ specifier: workspace:*
+ version: link:../fonts-open
'@hypit/ranking':
specifier: workspace:*
version: link:../ranking
@@ -3178,6 +3188,9 @@ importers:
'@hypit/composition':
specifier: workspace:*
version: link:../composition
+ '@hypit/fonts-open':
+ specifier: workspace:*
+ version: link:../fonts-open
'@hypit/studio-adapter':
specifier: workspace:*
version: link:../studio-adapter
diff --git a/skills/hypit/references/production/studio.md b/skills/hypit/references/production/studio.md
index b013946a..970ffec3 100644
--- a/skills/hypit/references/production/studio.md
+++ b/skills/hypit/references/production/studio.md
@@ -89,11 +89,38 @@ changes every consumer that uses it; create and select a separate authored insta
needs independent variation. Lists and records have a local draft with Apply and Reset; Apply writes
the complete validated value. Check save status and the resulting preview.
-Dragging a Selection boundary or Moment changes that identity in Script. Every Track consuming it
-then follows the changed semantic relation. A clock-based handle instead changes its declared time
-parameter. Use the displayed handles and their actual authority; a visible item is not automatically
-independently draggable. A derived or fixed value without a supported inverse may be read-only.
-Do not replace a semantic relation with guessed seconds just to make a rectangle move.
+Where groups position, size, fitting and layout. When groups timing, playback, trims and motion.
+How groups content, typography, color, effects and audio levels. Components name their own pages
+and sections within these questions. Numeric units sit outside the editable value: a width authored
+as `78%` keeps `%` when edited, while a fractional opacity may display as a percentage and write
+back as a fraction. Dropdowns can have readable option names and previews; their underlying value
+is what the Source receives. Color fields support exact hex values and suggested swatches.
+
+For catalog fonts, Caption, Typography and Ranking can expose the primary font family's dropdown
+through the selected Style. It edits the shared font declaration; its weight and style must be
+available in the chosen family. A local font continues to use its exact file. A project component
+can offer its own font or preset choices through Companion fields.
+
+Dragging a direct Selection or Moment changes that identity in Script. Every Track consuming it
+then follows the changed relation. The authored time form determines what the gesture changes:
+
+| Time form | Timeline editing |
+| --- | --- |
+| `during={story.selection.proof}` | Move both boundaries by the same number of semantic stops; the duration can change. Trim either boundary independently. |
+| `at={story.moment.reveal} for="8f"` | Move the Moment, or trim the trailing edge to change the duration. |
+| `until={story.moment.reveal} for="8f"` | Move the Moment, or trim the leading edge to change the duration. |
+| `at="2s" for="8f"` | Move the clock position, or trim the trailing duration; `until/for` works conversely. |
+| `instant="moment.cue"` or `instant="moment.cue + 2f"` with a bound Moment | Move the local offset while retaining the Moment; an omitted offset starts at zero. |
+| `start="..." end="..."` | Trim one endpoint's time expression, or move both by the same frame delta. Referenced Script markers stay in place. |
+
+A semantic stop is a distinct frame position occupied by word or structural boundaries. Select a
+semantic marker to see its exact anchors; when several share a frame, the Inspector offers the
+choices supported by its editable consumers. Direct Segment/Program spans follow their structural
+boundaries without timeline dragging. Components declare their own handles and writable fields.
+
+Clock-based dragging writes the changed value or offset in whole frames at the current frame rate.
+Unedited expressions retain their units: `2s` keeps its duration across frame-rate changes, while
+`60f` keeps its frame count. Direct semantic dragging changes the Script anchors instead.
Source edits outside Studio are observed too. If a stale UI edit conflicts with a newer file, read
the current Source and retry the intended change against it instead of overwriting the newer work.