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: complete structured Studio inspector editing

kashorin9fa9f088a8a7
diff --git a/examples/all-components-preview/recipes.svs b/examples/all-components-preview/recipes.svs
index c8906a10..69dcb890 100644
--- a/examples/all-components-preview/recipes.svs
+++ b/examples/all-components-preview/recipes.svs
@@ -11,7 +11,7 @@
board-border-color: #FFFFFF2E; board-border-width: 1; board-radius: 6;
board-shadow-x: 0; board-shadow-y: 6; board-shadow-blur: 18; board-shadow-spread: 0;
board-shadow-color: #00000059;
- rank-colors: #ff3f56|#ffa72d|#eadc2a|#84c654|#31add0;
+ rank-colors: ["#ff3f56", "#ffa72d", "#eadc2a", "#84c654", "#31add0"];
padding: 18; row-height: 74; row-gap: 10;
icon-size: 58; icon-radius: 13; icon-fit: contain;
stage-x: 0.5; stage-y: 0.5; stage-size: 96;
diff --git a/packages/audio-track-studio/src/index.ts b/packages/audio-track-studio/src/index.ts
index 0bd430db..32e5e281 100644
--- a/packages/audio-track-studio/src/index.ts
+++ b/packages/audio-track-studio/src/index.ts
@@ -32,22 +32,39 @@ export const audioTrackStudioAdapters: readonly StudioAdapter[] = [
output: { type: "AudioTrack", surface: "track", modules: ["@hypit/audio-track"] },
family: "audio", tone: "green", icon: "waveform",
timelineEdits: projectedWindowTimelineEdits({ start: "start", end: "end", duration: "for" }),
- parameters: [
- { name: "source", label: "Source", writable: false },
- { name: "start", label: "Start", writable: true },
- { name: "end", label: "End", writable: true },
- { name: "for", label: "For", writable: true },
- { name: "trim-start", label: "Trim source start", writable: true },
- { name: "trim-end", label: "Trim source end", writable: true },
+ bindings: [
+ { name: "source" },
+ { name: "start", writable: true },
+ { name: "end", writable: true },
+ { name: "for", writable: true },
+ { name: "trim-start", writable: true },
+ { name: "trim-end", writable: true },
+ { name: "playback", writable: true },
+ { name: "min-rate", writable: true },
+ { name: "max-rate", writable: true },
+ { name: "gain", writable: true },
+ { name: "fade-in", writable: true },
+ { name: "fade-out", writable: true },
+ ],
+ inspector: [
{
- name: "playback", label: "Playback", control: "select", writable: true,
- options: ["once", "once-start", "once-end", "loop", "loop-start", "loop-end", "stretch"],
+ binding: "playback", label: "Playback", domain: "how",
+ page: { id: "playback", label: "Playback" }, section: { id: "playback", label: "Playback" },
+ control: "select", options: ["once", "once-start", "once-end", "loop", "loop-start", "loop-end", "stretch"],
},
- { name: "min-rate", label: "Minimum rate", control: "number", writable: true },
- { name: "max-rate", label: "Maximum rate", control: "number", writable: true },
- { name: "gain", label: "Gain", control: "number", writable: true },
- { name: "fade-in", label: "Fade in", writable: true },
- { name: "fade-out", label: "Fade out", writable: true },
+ ...(["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,
+ })),
+ ...(["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,
+ })),
+ ...(["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,
+ })),
],
requiredValues: ["program"], project: projectAudio,
lane: { heightPx: 48 },
diff --git a/packages/caption-fine-studio/src/index.ts b/packages/caption-fine-studio/src/index.ts
index 7815c657..41b60212 100644
--- a/packages/caption-fine-studio/src/index.ts
+++ b/packages/caption-fine-studio/src/index.ts
@@ -5,53 +5,94 @@ import type {
StudioAdapter,
StudioAdapterContext,
StudioEntityDraft,
- StudioRecipeParameterDeclaration,
+ StudioInspectorFieldDeclaration,
} from "@hypit/studio-adapter";
import { requiredSurfaceValue, temporalLineageFor, textLayer } from "@hypit/studio-adapter";
-const WHERE_PROPERTIES = new Set([
- "stack-order", "x", "y", "width", "height", "anchor-x", "anchor-y", "align", "block-align",
- "inline-size", "wrap", "overflow", "max-lines", "max-words-per-line", "direction", "line-height",
- "letter-spacing", "word-gap",
-]);
+const styleSurface = captionFineMarkupSurfaces.find((surface) => surface.name === "style");
+const recipeVocabulary = styleSurface?.vocabulary.attributes
+ .find((attribute) => attribute.name === "recipe")?.recipe ?? [];
-const TIMED_ACTIVE_BOX_PROPERTIES = new Set([
- "active-box", "active-box-continuity", "active-box-enter", "active-box-exit", "active-box-transition-frames",
-]);
+function title(name: string): string {
+ return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
-function groupFor(name: string): "where" | "how" | "when" {
- if (WHERE_PROPERTIES.has(name)) return "where";
- if (name === "lead-frames" || name === "tail-frames" || name === "handoff"
- || name === "karaoke" || name === "karaoke-transition" || name === "active-underline"
- || name.startsWith("cue-enter") || name.startsWith("cue-exit") || name.startsWith("atom-")
- || name.startsWith("active-response") || name.startsWith("loop")
- || name === "slide-distance" || name === "active-scale" || TIMED_ACTIVE_BOX_PROPERTIES.has(name)) return "when";
- return "how";
+function valuesFor(property: typeof recipeVocabulary[number]): readonly string[] | undefined {
+ return "values" in property ? property.values : undefined;
}
-function sectionFor(name: string, group: "where" | "how" | "when"): string {
- if (group === "where") return ["x", "y", "width", "height", "anchor-x", "anchor-y", "stack-order"].includes(name)
- ? "region" : "flow";
- if (group === "when") {
- if (["lead-frames", "tail-frames", "handoff"].includes(name)) return "envelope";
- if (name.startsWith("cue-")) return "cue";
- if (name.startsWith("loop")) return "loop";
- return "token";
- }
- if (["size", "kerning", "caps", "text-transform"].includes(name)) return "typography";
- if (name === "background" || name === "border-color" || name === "border-width" || name === "padding"
- || name === "radius" || name.startsWith("cue-shadow")) return "cue-box";
- if (name.startsWith("active-box") || name.includes("underline")) return "decoration";
- return name.startsWith("active-") ? "active-paint" : "base-paint";
+type CaptionPlacement = Pick<StudioInspectorFieldDeclaration, "domain" | "page" | "section">;
+
+function captionPlace(domain: "where" | "how" | "when", page: string, section: string): CaptionPlacement {
+ return {
+ domain,
+ page: { id: page, label: title(page) },
+ section: { id: section, label: title(section) },
+ };
}
-const styleSurface = captionFineMarkupSurfaces.find((surface) => surface.name === "style");
-const recipeVocabulary = styleSurface?.vocabulary.attributes
- .find((attribute) => attribute.name === "recipe")?.recipe ?? [];
+const captionPlacement = new Map<string, CaptionPlacement>();
+function placeCaption(names: readonly string[], domain: "where" | "how" | "when", page: string, section: string): void {
+ for (const name of names) captionPlacement.set(name, captionPlace(domain, page, section));
+}
+
+placeCaption(["stack-order", "x", "y", "width", "height", "anchor-x", "anchor-y"], "where", "placement", "region");
+placeCaption([
+ "align", "block-align", "inline-size", "wrap", "overflow", "max-lines", "max-words-per-line", "direction",
+ "line-height", "letter-spacing", "word-gap",
+], "where", "flow", "flow");
+placeCaption(["size", "kerning", "caps", "text-transform"], "how", "text", "typography");
+placeCaption([
+ "fill", "opacity", "gradient-from", "gradient-to", "gradient-angle", "stroke-color", "stroke-width", "shadow-color",
+ "shadow-opacity", "shadow-x", "shadow-y", "shadow-blur", "shadow-spread", "long-shadow-color", "long-shadow-opacity",
+ "long-shadow-distance", "long-shadow-angle", "glow-color", "glow-opacity", "glow-blur", "glow-spread",
+], "how", "paint", "base-paint");
+placeCaption([
+ "active-fill", "active-opacity", "active-gradient-from", "active-gradient-to", "active-gradient-angle",
+ "active-stroke-color", "active-stroke-width", "active-shadow-color", "active-shadow-opacity", "active-shadow-x",
+ "active-shadow-y", "active-shadow-blur", "active-shadow-spread", "active-long-shadow-color",
+ "active-long-shadow-opacity", "active-long-shadow-distance", "active-long-shadow-angle", "active-glow-color",
+ "active-glow-opacity", "active-glow-blur", "active-glow-spread",
+], "how", "paint", "active-paint");
+placeCaption([
+ "background", "border-color", "border-width", "padding", "radius", "cue-shadow-color", "cue-shadow-opacity",
+ "cue-shadow-x", "cue-shadow-y", "cue-shadow-blur", "cue-shadow-spread",
+], "how", "cue-box", "cue-box");
+placeCaption([
+ "underline", "underline-color", "underline-thickness", "underline-offset", "active-underline-color",
+ "active-underline-thickness", "active-underline-offset", "active-box-background", "active-box-border-color",
+ "active-box-border-width", "active-box-padding", "active-box-radius",
+], "how", "decoration", "decoration");
+placeCaption(["lead-frames", "tail-frames", "handoff"], "when", "cue", "envelope");
+placeCaption(["cue-enter", "cue-enter-frames", "cue-exit", "cue-exit-frames"], "when", "cue", "cue");
+placeCaption([
+ "karaoke", "karaoke-transition", "active-underline", "active-box", "active-box-continuity", "active-box-enter",
+ "active-box-exit", "active-box-transition-frames", "atom-enter", "atom-enter-frames", "atom-exit", "atom-exit-frames",
+ "atom-reveal", "active-response", "active-response-frames", "active-scale", "slide-distance",
+], "when", "token", "token");
+placeCaption(["loop", "loop-target", "loop-period-frames", "loop-intensity"], "when", "loop", "loop");
+
+const captionColorProperties = new Set([
+ "fill", "gradient-from", "gradient-to", "stroke-color", "shadow-color", "long-shadow-color", "glow-color",
+ "active-fill", "active-gradient-from", "active-gradient-to", "active-stroke-color", "active-shadow-color",
+ "active-long-shadow-color", "active-glow-color", "background", "border-color", "cue-shadow-color", "underline-color",
+ "active-underline-color", "active-box-background", "active-box-border-color",
+]);
+const captionTextProperties = new Set(["loop"]);
-export const captionFineRecipeParameters: readonly StudioRecipeParameterDeclaration[] = recipeVocabulary.map((property) => {
- const group = groupFor(property.name);
- return { name: property.name, group, section: sectionFor(property.name, group) };
+export const captionFineInspectorFields: readonly StudioInspectorFieldDeclaration[] = recipeVocabulary.map((property) => {
+ const placement = captionPlacement.get(property.name);
+ if (placement === undefined) throw new Error(`Caption Studio has no explicit Inspector declaration for ${property.name}.`);
+ const options = valuesFor(property);
+ return {
+ binding: `program.${property.name}`,
+ label: title(property.name),
+ ...placement,
+ summary: property.summary,
+ control: options !== undefined ? "select" : captionColorProperties.has(property.name) ? "color"
+ : captionTextProperties.has(property.name) ? "text" : "number",
+ ...(options === undefined ? {} : { options }),
+ };
});
function captionDocument(context: StudioAdapterContext, id: string): CaptionDocument | undefined {
@@ -117,12 +158,13 @@ export const captionFineStudioAdapters: readonly StudioAdapter[] = [
id: "track", role: "track",
output: { type: "VisualTrack", surface: "track", modules: ["@hypit/caption-fine"] },
family: "caption", tone: "magenta", icon: "captions",
- parameters: [
+ bindings: [
{
- name: "program", label: "Program", writable: false,
- recipe: { through: ["recipe"], parameters: captionFineRecipeParameters },
+ name: "program",
+ recipe: { through: ["recipe"], bindings: recipeVocabulary.map(({ name }) => ({ name })) },
},
],
+ inspector: captionFineInspectorFields,
requiredValues: ["schedule"], project: projectCaption,
lane: { heightPx: 48 },
},
diff --git a/packages/caption-fine-studio/test/adapter.test.ts b/packages/caption-fine-studio/test/adapter.test.ts
index 688a59f3..3bab822e 100644
--- a/packages/caption-fine-studio/test/adapter.test.ts
+++ b/packages/caption-fine-studio/test/adapter.test.ts
@@ -5,15 +5,15 @@ import type { FineCaptionSchedule } from "@hypit/caption-fine";
import type { CaptionDocument } from "@hypit/narrative";
import type { StudioAdapterContext, StudioEntityDraft } from "@hypit/studio-adapter";
-import { captionFineRecipeParameters, captionFineStudioAdapters } from "../src/index.js";
+import { captionFineInspectorFields, captionFineStudioAdapters } from "../src/index.js";
test("Caption Companion owns Inspector grouping", () => {
- const declared = (name: string) => captionFineRecipeParameters.find((property) => property.name === name);
- assert.equal(declared("x")?.group, "where");
- assert.equal(declared("x")?.section, "region");
- assert.equal(declared("cue-shadow-blur")?.group, "how");
- assert.equal(declared("active-box-enter")?.group, "when");
- assert.equal(declared("lead-frames")?.section, "envelope");
+ const declared = (name: string) => captionFineInspectorFields.find((field) => field.binding === `program.${name}`);
+ assert.equal(declared("x")?.domain, "where");
+ assert.equal(declared("x")?.section.id, "region");
+ assert.equal(declared("cue-shadow-blur")?.domain, "how");
+ assert.equal(declared("active-box-enter")?.domain, "when");
+ assert.equal(declared("lead-frames")?.section.id, "envelope");
});
test("Caption Companion projects Cue text and Style from public domain values", () => {
diff --git a/packages/comment-sticker-studio/src/index.ts b/packages/comment-sticker-studio/src/index.ts
index 1af11b9a..d6a6ad1c 100644
--- a/packages/comment-sticker-studio/src/index.ts
+++ b/packages/comment-sticker-studio/src/index.ts
@@ -1,31 +1,71 @@
import { commentStickerMarkupSurfaces } from "@hypit/comment-sticker";
import type { CommentStickerProgram } from "@hypit/comment-sticker";
-import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft, StudioParameterDeclaration, StudioRecipeParameterDeclaration } from "@hypit/studio-adapter";
+import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft, StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-adapter";
import { artifactPreview, childEntities, previewLayer, projectedWindowTimelineEdits, requiredSurfaceValue, temporalLineageFor, textLayer } from "@hypit/studio-adapter";
-const frameParameters: readonly StudioParameterDeclaration[] = [
- { name: "within", label: "Within", writable: false },
- { name: "left", label: "Left", writable: true },
- { name: "top", label: "Top", writable: true },
- { name: "right", label: "Right", writable: true },
- { name: "bottom", label: "Bottom", writable: true },
- { name: "x", label: "X", writable: true },
- { name: "y", label: "Y", writable: true },
- { name: "width", label: "Width", writable: true },
- { name: "height", label: "Height", writable: true },
+const frameParameters: readonly StudioSourceBindingDeclaration[] = [
+ { name: "within" },
+ ...["left", "top", "right", "bottom", "x", "y", "width", "height"].map((name) => ({ name, writable: true })),
];
-const commentRecipe: readonly StudioRecipeParameterDeclaration[] = (commentStickerMarkupSurfaces
+const commentProperties = (commentStickerMarkupSurfaces
.find((surface) => surface.name === "style")?.vocabulary.attributes
- .find((attribute) => attribute.name === "recipe")?.recipe ?? []).map((property) => {
- const when = property.name.startsWith("enter") || property.name.startsWith("exit");
- const where = /(?:width|height|padding|offset|size|gap|stack)/u.test(property.name);
- return {
- name: property.name,
- group: when ? "when" : where ? "where" : "how",
- section: when ? "motion" : where ? "layout" : "appearance",
- };
- });
+ .find((attribute) => attribute.name === "recipe")?.recipe ?? []);
+
+function title(name: string): string {
+ return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+
+function valuesFor(property: typeof commentProperties[number]): readonly string[] | undefined {
+ return "values" in property ? property.values : undefined;
+}
+
+type CommentPlacement = Pick<StudioInspectorFieldDeclaration, "domain" | "page" | "section">;
+
+function commentPlace(domain: "where" | "how" | "when", page: string, section: string): CommentPlacement {
+ const id = section.toLowerCase().replaceAll(" ", "-");
+ return { domain, page: { id: page.toLowerCase(), label: page }, section: { id, label: section } };
+}
+
+const commentPlacement = new Map<string, CommentPlacement>();
+function placeComment(names: readonly string[], domain: "where" | "how" | "when", page: string, section: string): void {
+ for (const name of names) commentPlacement.set(name, commentPlace(domain, page, section));
+}
+
+placeComment(["stack-order"], "where", "Layout", "Stacking");
+placeComment(["padding-x", "padding-y", "gap", "radius"], "where", "Layout", "Card");
+placeComment(["tail-width", "tail-height", "tail-offset-x"], "where", "Layout", "Tail");
+placeComment(["avatar-size", "avatar-border-width"], "where", "Layout", "Avatar");
+placeComment([
+ "header-size", "header-line-height", "body-size", "body-line-height", "body-max-lines", "meta-size", "meta-line-height",
+], "where", "Layout", "Copy");
+placeComment([
+ "background", "border-color", "border-width", "rotation", "shadow-color", "shadow-x", "shadow-y", "shadow-blur",
+ "shadow-spread", "tail", "avatar-fallback", "avatar-border-color", "avatar-background", "avatar-text-color",
+], "how", "Appearance", "Card");
+placeComment(["header-weight", "header-color", "body-weight", "body-color", "meta-weight", "meta-color"], "how", "Appearance", "Copy");
+placeComment([
+ "enter", "enter-frames", "enter-offset-y", "enter-start-scale", "enter-rotation-delta", "enter-easing",
+], "when", "Motion", "Enter");
+placeComment(["exit", "exit-frames", "exit-offset-y", "exit-easing"], "when", "Motion", "Exit");
+placeComment(["hold", "hold-amplitude-y", "hold-rotation-amplitude", "hold-period-frames"], "when", "Motion", "Hold");
+
+const commentColorProperties = new Set([
+ "background", "border-color", "shadow-color", "avatar-border-color", "avatar-background", "avatar-text-color",
+ "header-color", "body-color", "meta-color",
+]);
+
+const commentInspector: readonly StudioInspectorFieldDeclaration[] = commentProperties.map((property) => {
+ const placement = commentPlacement.get(property.name);
+ if (placement === undefined) throw new Error(`Comment Sticker Studio has no explicit Inspector declaration for ${property.name}.`);
+ const options = valuesFor(property);
+ return {
+ binding: `style.${property.name}`, label: title(property.name), ...placement,
+ ...(property.summary === undefined ? {} : { summary: property.summary }),
+ control: options !== undefined ? "select" : commentColorProperties.has(property.name) ? "color" : "number",
+ ...(options === undefined ? {} : { options }),
+ };
+});
function projectComments(context: StudioAdapterContext): readonly StudioEntityDraft[] {
const program = requiredSurfaceValue(context, "program") as CommentStickerProgram;
@@ -63,20 +103,26 @@ export const commentStickerStudioAdapters: readonly StudioAdapter[] = [
output: { type: "VisualTrack", surface: "track", modules: ["@hypit/comment-sticker"] },
family: "comment-sticker", tone: "orange", icon: "component",
timelineEdits: projectedWindowTimelineEdits({ start: "start", end: "end", duration: "for" }),
- parameters: [
- { name: "frame", label: "Frame", writable: false, referenced: frameParameters },
+ bindings: [
+ { name: "frame", referenced: frameParameters },
{
- name: "style", label: "Style", writable: false,
- recipe: { through: ["recipe"], parameters: commentRecipe },
+ name: "style",
+ recipe: { through: ["recipe"], bindings: commentProperties.map(({ name }) => ({ name })) },
},
- { name: "comment", label: "Comment", writable: true },
- { name: "author", label: "Author", writable: true },
- { name: "header", label: "Header", writable: true },
- { name: "meta", label: "Meta", writable: true },
- { name: "avatar", label: "Avatar", writable: false },
- { name: "start", label: "Start", writable: true },
- { name: "end", label: "End", writable: true },
- { name: "for", label: "For", writable: true },
+ ...["comment", "author", "header", "meta"].map((name) => ({ name, writable: true })),
+ { name: "avatar" },
+ ...["start", "end", "for"].map((name) => ({ name, writable: true })),
+ ],
+ 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,
+ })),
+ ...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,
+ })),
],
requiredValues: ["program"], project: projectComments,
poster: { source: "surface-preview" },
diff --git a/packages/deck-track-studio/src/index.ts b/packages/deck-track-studio/src/index.ts
index c52bf838..4f5d7bdd 100644
--- a/packages/deck-track-studio/src/index.ts
+++ b/packages/deck-track-studio/src/index.ts
@@ -1,19 +1,69 @@
import { depthStackMarkupSurfaces } from "@hypit/deck-track";
import type { DepthStackProgram } from "@hypit/deck-track";
-import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft, StudioRecipeParameterDeclaration } from "@hypit/studio-adapter";
+import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft, StudioInspectorFieldDeclaration } from "@hypit/studio-adapter";
import { projectedPointTimelineEdits, requiredSurfaceValue, temporalLineageFor } from "@hypit/studio-adapter";
-const deckAppearanceRecipe: readonly StudioRecipeParameterDeclaration[] = (depthStackMarkupSurfaces
+const deckProperties = (depthStackMarkupSurfaces
.find((surface) => surface.name === "track")?.vocabulary.attributes
- .find((attribute) => attribute.name === "appearance")?.recipe ?? []).map((property) => {
- const when = property.name.includes("frames") || property.name.includes("easing") || property.name.includes("duration");
- const where = /(?:^|[-])(x|y|scale|rotation|stacking|visible)(?:$|[-])/u.test(property.name);
- return {
- name: property.name,
- group: when ? "when" : where ? "where" : "how",
- section: when ? "motion" : where ? "depth" : "appearance",
- };
- });
+ .find((attribute) => attribute.name === "appearance")?.recipe ?? []);
+
+function title(name: string): string {
+ return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+
+function valuesFor(property: typeof deckProperties[number]): readonly string[] | undefined {
+ return "values" in property ? property.values : undefined;
+}
+
+type DeckPlacement = Pick<StudioInspectorFieldDeclaration, "domain" | "page" | "section">;
+
+function deckPlace(domain: "where" | "how" | "when", page: string, section: string): DeckPlacement {
+ const id = section.toLowerCase().replaceAll(" ", "-");
+ return { domain, page: { id: page.toLowerCase(), label: page }, section: { id, label: section } };
+}
+
+const deckPlacement = new Map<string, DeckPlacement>();
+function placeDeck(names: readonly string[], domain: "where" | "how" | "when", page: string, section: string): void {
+ for (const name of names) deckPlacement.set(name, deckPlace(domain, page, section));
+}
+
+placeDeck([
+ "visible-previous", "visible-next", "wrap", "current-x", "current-y", "current-scale", "current-rotation",
+ "current-stacking", "previous-x-step", "previous-y-step", "previous-scale-step", "previous-rotation-step",
+ "previous-rotation-mode", "previous-stacking-step", "next-x-step", "next-y-step", "next-scale-step",
+ "next-rotation-step", "next-rotation-mode", "next-stacking-step",
+], "where", "Depth", "Card Stack");
+placeDeck(["stack-order"], "where", "Frame", "Stacking");
+placeDeck(["clip", "radius", "padding"], "where", "Frame", "Geometry");
+placeDeck([
+ "fit", "frame-x", "frame-y", "content-x", "content-y", "fit-offset-x", "fit-offset-y", "fit-constraint",
+], "where", "Frame", "Fit");
+placeDeck([
+ "current-opacity", "current-brightness", "current-contrast", "current-saturation", "previous-opacity-step",
+ "next-opacity-step", "border-width", "border-style", "border-color", "shadows", "frame-paint", "opacity",
+ "blur", "brightness", "contrast", "saturation",
+], "how", "Appearance", "Paint");
+placeDeck(["playback", "trim-start", "trim-end", "playback-future", "playback-past"], "how", "Appearance", "Playback");
+placeDeck(["reflow-frames", "reflow-easing"], "when", "Motion", "Reflow");
+placeDeck(["enter", "enter-frames", "enter-easing", "enter-direction", "enter-amount", "enter-origin"], "when", "Motion", "Enter");
+placeDeck(["sustain"], "when", "Motion", "Sustain");
+placeDeck(["exit", "exit-frames", "exit-easing", "exit-direction", "exit-amount", "exit-origin"], "when", "Motion", "Exit");
+
+const deckColorProperties = new Set(["border-color"]);
+const deckTextProperties = new Set(["padding", "shadows", "frame-paint", "sustain"]);
+
+const deckInspector: readonly StudioInspectorFieldDeclaration[] = deckProperties.map((property) => {
+ const placement = deckPlacement.get(property.name);
+ if (placement === undefined) throw new Error(`Deck Studio has no explicit Inspector declaration for ${property.name}.`);
+ const options = valuesFor(property);
+ return {
+ binding: `appearance.${property.name}`, label: title(property.name), ...placement,
+ ...(property.summary === undefined ? {} : { summary: property.summary }),
+ control: options !== undefined ? "select" : deckColorProperties.has(property.name) ? "color"
+ : deckTextProperties.has(property.name) ? "text" : "number",
+ ...(options === undefined ? {} : { options }),
+ };
+});
function cardTitle(card: DepthStackProgram["cards"][number]): string {
if (card.label.kind === "none") return card.id;
@@ -62,14 +112,21 @@ export const deckTrackStudioAdapters: readonly StudioAdapter[] = [
output: { type: "VisualTrack", surface: "track", modules: ["@hypit/deck-track"] },
family: "deck", tone: "orange", icon: "layers", requiredValues: ["program"],
timelineEdits: projectedPointTimelineEdits(),
- parameters: [
- { name: "source", label: "Source", writable: false },
- { name: "extent", label: "Extent", writable: false },
+ bindings: [
+ { name: "source" },
+ { name: "extent" },
+ {
+ name: "appearance",
+ recipe: { bindings: deckProperties.map(({ name }) => ({ name })) },
+ },
+ { name: "label", writable: true },
+ ],
+ inspector: [
+ ...deckInspector,
{
- name: "appearance", label: "Appearance", writable: false,
- recipe: { parameters: deckAppearanceRecipe },
+ binding: "label", label: "Label", domain: "how",
+ page: { id: "label", label: "Label" }, section: { id: "label", label: "Label" }, control: "text",
},
- { name: "label", label: "Label", writable: true },
],
project: projectDeck,
lane: { heightPx: 52 },
diff --git a/packages/markup/src/types.ts b/packages/markup/src/types.ts
index c447064a..f8621886 100644
--- a/packages/markup/src/types.ts
+++ b/packages/markup/src/types.ts
@@ -1,10 +1,12 @@
import type {
+ CanonicalValue,
ModuleRef,
ResolvedModuleClosure,
SourceRange,
StoredValue,
TypeRef,
TypedRecord,
+ ValueSchema,
} from "@hypit/protocol";
import type {
AuthorComponent,
@@ -126,8 +128,10 @@ export type SurfaceRecipePropertyVocabulary = {
readonly name: string;
readonly required: boolean;
readonly summary: string;
+ /** The author value's public structure; it contains no editor presentation. */
+ readonly schema?: ValueSchema;
readonly values?: readonly string[];
- readonly fallback?: string;
+ readonly fallback?: CanonicalValue;
};
export type SurfaceAttributeVocabulary = {
diff --git a/packages/media-track-studio/src/index.ts b/packages/media-track-studio/src/index.ts
index 661c82e7..39b6cee6 100644
--- a/packages/media-track-studio/src/index.ts
+++ b/packages/media-track-studio/src/index.ts
@@ -4,40 +4,92 @@ import type {
StudioAdapter,
StudioAdapterContext,
StudioEntityDraft,
+ StudioInspectorFieldDeclaration,
StudioMaterialPreview,
- StudioParameterDeclaration,
- StudioRecipeParameterDeclaration,
+ StudioSourceBindingDeclaration,
} from "@hypit/studio-adapter";
import { artifactPreview, childEntities, previewLayer, projectedWindowTimelineEdits, requiredSurfaceValue, temporalLineageFor } from "@hypit/studio-adapter";
-const frameParameters: readonly StudioParameterDeclaration[] = [
- { name: "within", label: "Within", writable: false },
- { name: "left", label: "Left", writable: true },
- { name: "top", label: "Top", writable: true },
- { name: "right", label: "Right", writable: true },
- { name: "bottom", label: "Bottom", writable: true },
- { name: "x", label: "X", writable: true },
- { name: "y", label: "Y", writable: true },
- { name: "width", label: "Width", writable: true },
- { name: "height", label: "Height", writable: true },
+const frameParameters: readonly StudioSourceBindingDeclaration[] = [
+ { name: "within" },
+ { name: "left", writable: true },
+ { name: "top", writable: true },
+ { name: "right", writable: true },
+ { name: "bottom", writable: true },
+ { name: "x", writable: true },
+ { name: "y", writable: true },
+ { name: "width", writable: true },
+ { name: "height", writable: true },
];
-const extentParameters: readonly StudioParameterDeclaration[] = [
- { name: "width", label: "Width", control: "number", writable: true, unit: "px" },
- { name: "height", label: "Height", control: "number", writable: true, unit: "px" },
+const extentParameters: readonly StudioSourceBindingDeclaration[] = [
+ { name: "width", writable: true },
+ { name: "height", writable: true },
];
const mediaTrackSurface = mediaTrackMarkupSurfaces.find((surface) => surface.name === "track");
const mediaItemAttributes = mediaTrackSurface?.vocabulary.children?.find((child) => child.tag === "Item")?.attributes ?? [];
-function mediaRecipe(name: "appearance" | "motion"): readonly StudioRecipeParameterDeclaration[] {
+function title(name: string): string {
+ return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+
+function valuesFor(property: { readonly name: string }): readonly string[] | undefined {
+ return "values" in property ? (property as { readonly values: readonly string[] }).values : undefined;
+}
+
+type MediaPlacement = Pick<StudioInspectorFieldDeclaration, "domain" | "page" | "section">;
+
+function mediaPlace(domain: "where" | "how" | "when", page: string, section: string): MediaPlacement {
+ const id = section.toLowerCase().replaceAll(" ", "-");
+ return { domain, page: { id: page.toLowerCase(), label: page }, section: { id, label: section } };
+}
+
+const mediaPlacement = new Map<string, MediaPlacement>();
+function placeMedia(names: readonly string[], domain: "where" | "how" | "when", page: string, section: string): void {
+ for (const name of names) mediaPlacement.set(name, mediaPlace(domain, page, section));
+}
+
+placeMedia([
+ "fit", "frame-x", "frame-y", "content-x", "content-y", "fit-offset-x", "fit-offset-y", "fit-constraint",
+], "where", "Fit", "Fit");
+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(["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");
+placeMedia(["exit", "exit-frames", "exit-easing", "exit-direction", "exit-amount", "exit-origin"], "when", "Exit", "Exit");
+
+const mediaColorProperties = new Set(["border-color"]);
+const mediaTextProperties = new Set(["padding", "shadows", "frame-paint", "sustain"]);
+
+function mediaRecipe(name: "appearance" | "motion"): {
+ readonly bindings: readonly { readonly name: string }[];
+ readonly inspector: readonly StudioInspectorFieldDeclaration[];
+} {
const attribute = mediaItemAttributes.find((candidate) => candidate.name === name);
const properties = attribute !== undefined && "recipe" in attribute ? attribute.recipe : [];
- return properties.map((property) => ({
- name: property.name,
- group: name === "motion" ? "when" : property.name === "stack-order" ? "where" : "how",
- section: name === "motion" ? "lifecycle" : property.name === "stack-order" ? "stacking" : "appearance",
- }));
+ return {
+ bindings: properties.map(({ name: property }) => ({ name: property })),
+ inspector: properties.map((property) => {
+ const placement = mediaPlacement.get(property.name);
+ if (placement === undefined) throw new Error(`Media Studio has no explicit Inspector declaration for ${property.name}.`);
+ const options = valuesFor(property);
+ const control = options !== undefined ? "select" as const
+ : mediaColorProperties.has(property.name) ? "color" as const
+ : mediaTextProperties.has(property.name) ? "text" as const : "number" as const;
+ return {
+ binding: `${name}.${property.name}`,
+ label: title(property.name),
+ ...placement,
+ ...(property.summary === undefined ? {} : { summary: property.summary }),
+ control,
+ ...(options === undefined ? {} : { options }),
+ };
+ }),
+ };
}
const mediaAppearanceRecipe = mediaRecipe("appearance");
@@ -105,42 +157,68 @@ function projectMedia(context: StudioAdapterContext): readonly StudioEntityDraft
});
}
-const commonParameters: readonly StudioParameterDeclaration[] = [
- { name: "start", label: "Start", writable: true },
- { name: "end", label: "End", writable: true },
- { name: "for", label: "For", writable: true },
- { name: "source-audio", label: "Source audio", writable: true },
- { name: "audio-gain", label: "Audio gain", control: "number", writable: true },
- { name: "until", label: "Until", writable: false },
+const commonBindings: readonly StudioSourceBindingDeclaration[] = [
+ { name: "start", writable: true },
+ { name: "end", writable: true },
+ { name: "for", writable: true },
+ { name: "source-audio", writable: true },
+ { name: "audio-gain", writable: true },
+ { name: "until" },
+ { name: "until-boundary", writable: true },
+];
+
+const commonInspector: readonly StudioInspectorFieldDeclaration[] = [
{
- name: "until-boundary", label: "Until boundary", control: "select", writable: true,
- options: ["start", "end"],
+ binding: "audio-gain", label: "Audio Gain", domain: "how",
+ page: { id: "audio", label: "Audio" }, section: { id: "audio", label: "Audio" }, control: "number",
+ },
+ {
+ binding: "until-boundary", label: "Until Boundary", domain: "when",
+ page: { id: "boundary", label: "Boundary" }, section: { id: "boundary", label: "Boundary" },
+ control: "select", options: ["start", "end"],
},
];
+const frameSizeParameters = new Set(["width", "height"]);
+
export const mediaTrackStudioAdapters: readonly StudioAdapter[] = [
{
id: "visual", role: "track",
output: { type: "VisualTrack", surface: "track", modules: ["@hypit/media-track"] },
family: "media", tone: "blue", icon: "video",
timelineEdits: projectedWindowTimelineEdits({ start: "start", end: "end", duration: "for" }),
- parameters: [
- ...commonParameters,
- { name: "extent", label: "Extent", writable: false, referenced: extentParameters },
- { name: "clip", label: "Clip", writable: false },
- { name: "image", label: "Image", writable: false },
- { name: "media", label: "Media", writable: false },
- { name: "surface", label: "Surface", writable: false },
- { name: "frame", label: "Frame", writable: false, referenced: frameParameters },
+ bindings: [
+ ...commonBindings,
+ { name: "extent", referenced: extentParameters },
+ { name: "clip" },
+ { name: "image" },
+ { name: "media" },
+ { name: "surface" },
+ { name: "frame", referenced: frameParameters },
{
- name: "appearance", label: "Appearance", writable: false,
- recipe: { parameters: mediaAppearanceRecipe },
+ name: "appearance",
+ recipe: { bindings: mediaAppearanceRecipe.bindings },
},
{
- name: "motion", label: "Motion", writable: false,
- recipe: { parameters: mediaMotionRecipe },
+ name: "motion",
+ recipe: { bindings: mediaMotionRecipe.bindings },
},
],
+ inspector: [
+ ...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,
+ })),
+ ...extentParameters.map(({ name }) => ({
+ binding: `extent.${name}`, label: title(name), domain: "where" as const,
+ page: { id: "size", label: "Size" }, section: { id: "extent", label: "Source Extent" },
+ control: "number" as const, unit: "px",
+ })),
+ ...mediaAppearanceRecipe.inspector,
+ ...mediaMotionRecipe.inspector,
+ ...commonInspector,
+ ],
requiredValues: ["program"], project: projectMedia,
lane: { heightPx: 76 },
},
@@ -149,7 +227,8 @@ export const mediaTrackStudioAdapters: readonly StudioAdapter[] = [
output: { type: "AudioTrack", surface: "track", modules: ["@hypit/media-track"] },
family: "media-audio", tone: "green", icon: "waveform",
timelineEdits: projectedWindowTimelineEdits({ start: "start", end: "end", duration: "for" }),
- parameters: commonParameters,
+ bindings: commonBindings,
+ inspector: commonInspector,
requiredValues: ["program"], project: projectMedia,
lane: { heightPx: 48 },
},
diff --git a/packages/protocol/src/value.ts b/packages/protocol/src/value.ts
index 3e3e8d1a..603068bd 100644
--- a/packages/protocol/src/value.ts
+++ b/packages/protocol/src/value.ts
@@ -36,6 +36,8 @@ export type ValueSchema =
readonly enum?: readonly string[];
readonly minLength?: number;
readonly maxLength?: number;
+ /** UI-neutral semantic format shared by authoring, validation and tools. */
+ readonly format?: "color";
}
| {
readonly kind: "literal";
diff --git a/packages/ranking-studio/src/index.ts b/packages/ranking-studio/src/index.ts
index caca8358..1e654dd7 100644
--- a/packages/ranking-studio/src/index.ts
+++ b/packages/ranking-studio/src/index.ts
@@ -1,38 +1,97 @@
import { rankingMarkupSurfaces } from "@hypit/ranking";
import type { RankingProgram, RankingSchedule } from "@hypit/ranking";
-import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft, StudioParameterDeclaration, StudioRecipeParameterDeclaration } from "@hypit/studio-adapter";
+import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft, StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-adapter";
import { artifactPreview, previewLayer, projectedPointTimelineEdits, requiredSurfaceValue, selectionWindowTimelineEdits, temporalLineageFor } from "@hypit/studio-adapter";
-const frameParameters: readonly StudioParameterDeclaration[] = [
- { name: "within", label: "Within", writable: false },
- { name: "left", label: "Left", writable: true },
- { name: "top", label: "Top", writable: true },
- { name: "right", label: "Right", writable: true },
- { name: "bottom", label: "Bottom", writable: true },
- { name: "x", label: "X", writable: true },
- { name: "y", label: "Y", writable: true },
- { name: "width", label: "Width", writable: true },
- { name: "height", label: "Height", writable: true },
+const frameParameters: readonly StudioSourceBindingDeclaration[] = [
+ { name: "within" },
+ ...["left", "top", "right", "bottom", "x", "y", "width", "height"].map((name) => ({ name, writable: true })),
];
-function rankingRecipe(surface: "column-style" | "tier-style" | "top-three-style"): readonly StudioRecipeParameterDeclaration[] {
- const properties = rankingMarkupSurfaces.find((candidate) => candidate.name === surface)
+function rankingProperties(surface: "column-style" | "tier-style" | "top-three-style") {
+ return rankingMarkupSurfaces.find((candidate) => candidate.name === surface)
?.vocabulary.attributes.find((attribute) => attribute.name === "recipe")?.recipe ?? [];
- return properties.map((property) => {
- const when = property.name.includes("frames") || property.name.includes("easing") || property.name.includes("fade");
- const where = /(?:^|[-])(x|y|width|height|size|gap|padding|stack|rows|radius)(?:$|[-])/u.test(property.name);
+}
+
+function title(name: string): string {
+ return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+
+type RankingInspectorPlacement = Pick<StudioInspectorFieldDeclaration, "domain" | "page" | "section">;
+
+function place(domain: "where" | "how" | "when", page: string, section: string): RankingInspectorPlacement {
+ return {
+ domain,
+ page: { id: page.toLowerCase().replaceAll(" ", "-"), label: page },
+ section: { id: section.toLowerCase().replaceAll(" ", "-"), label: section },
+ };
+}
+
+const rankingInspectorPlacement = {
+ rows: place("how", "Board", "Tier Rows"),
+ "rank-colors": place("how", "Board", "Rank Badges"),
+ "slot-colors": place("how", "Board", "Podium Slots"),
+ "font-size": place("how", "Text", "Typography"),
+ "font-weight": place("how", "Text", "Typography"),
+ "text-color": place("how", "Text", "Typography"),
+ "line-height": place("how", "Text", "Typography"),
+ "board-background": place("how", "Board", "Board Paint"),
+ "board-border-color": place("how", "Board", "Board Paint"),
+ "board-border-width": place("how", "Board", "Board Paint"),
+ "board-radius": place("how", "Board", "Board Paint"),
+ "board-shadow-x": place("how", "Board", "Board Shadow"),
+ "board-shadow-y": place("how", "Board", "Board Shadow"),
+ "board-shadow-blur": place("how", "Board", "Board Shadow"),
+ "board-shadow-spread": place("how", "Board", "Board Shadow"),
+ "board-shadow-color": place("how", "Board", "Board Shadow"),
+ "appear-frames": place("when", "Motion", "Entrance"),
+ "move-frames": place("when", "Motion", "Movement"),
+ "motion-easing": place("when", "Motion", "Movement"),
+ "label-width": place("where", "Layout", "Rows"),
+ padding: place("where", "Layout", "Board"),
+ "row-height": place("where", "Layout", "Rows"),
+ "row-gap": place("where", "Layout", "Rows"),
+ "cell-gap": place("where", "Layout", "Rows"),
+ "icon-size": place("where", "Layout", "Items"),
+ "icon-radius": place("how", "Board", "Items"),
+ "icon-fit": place("how", "Board", "Items"),
+ "stage-x": place("where", "Stage", "Position"),
+ "stage-y": place("where", "Stage", "Position"),
+ "stage-size": place("where", "Stage", "Size"),
+ "center-x": place("where", "Layout", "Podium"),
+ "baseline-y": place("where", "Layout", "Podium"),
+ "slot-gap": place("where", "Layout", "Podium"),
+ "ring-width": place("how", "Board", "Podium Slots"),
+ "label-gap": place("where", "Layout", "Podium"),
+ "board-stack": place("where", "Stacking", "Layers"),
+ "stage-stack": place("where", "Stacking", "Layers"),
+ "item-stack": place("where", "Stacking", "Layers"),
+ "appear-gain": place("how", "Sound", "Levels"),
+ "move-gain": place("how", "Sound", "Levels"),
+ "sound-fade-frames": place("when", "Sound", "Envelope"),
+} as const satisfies Readonly<Record<string, RankingInspectorPlacement>>;
+
+function rankingInspector(surface: "column-style" | "tier-style" | "top-three-style"): readonly StudioInspectorFieldDeclaration[] {
+ return 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 {
- name: property.name,
- group: when ? "when" : where ? "where" : "how",
- section: when ? "motion" : where ? "layout" : "appearance",
+ binding: `style.${property.name}`,
+ label: title(property.name),
+ ...placement,
+ ...(property.summary === undefined ? {} : { summary: property.summary }),
};
});
}
-function rankingStyle(surface: "column-style" | "tier-style" | "top-three-style"): StudioParameterDeclaration {
+function rankingStyle(surface: "column-style" | "tier-style" | "top-three-style"): StudioSourceBindingDeclaration {
return {
- name: "style", label: "Style", writable: false,
- recipe: { through: ["recipe"], parameters: rankingRecipe(surface) },
+ name: "style",
+ recipe: { through: ["recipe"], bindings: rankingProperties(surface).map(({ name, schema, fallback }) => ({
+ name,
+ schema,
+ ...(fallback === undefined ? {} : { fallback }),
+ })) },
};
}
@@ -87,22 +146,30 @@ function projectRanking(context: StudioAdapterContext): readonly StudioEntityDra
return [group, ...reveals];
}
-const commonParameters: readonly StudioParameterDeclaration[] = [
- { name: "frame", label: "Frame", writable: false, referenced: frameParameters },
- { name: "appear-sound", label: "Appear sound", writable: false },
- { name: "move-sound", label: "Move sound", writable: false },
+const commonBindings: readonly StudioSourceBindingDeclaration[] = [
+ { name: "frame", referenced: frameParameters },
+ { name: "appear-sound" },
+ { name: "move-sound" },
];
+const frameInspector: readonly StudioInspectorFieldDeclaration[] = frameParameters
+ .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",
+ }));
+
export const rankingStudioAdapters: readonly StudioAdapter[] = [
{
id: "column", role: "track",
output: { type: "VisualTrack", surface: "column", modules: ["@hypit/ranking"] },
family: "ranking", tone: "orange", label: "Ranking", icon: "ranking", requiredValues: ["schedule", "program"],
timelineEdits: selectionWindowTimelineEdits(),
- parameters: [
- ...commonParameters,
+ bindings: [
+ ...commonBindings,
rankingStyle("column-style"),
],
+ inspector: [...frameInspector, ...rankingInspector("column-style")],
poster: { source: "surface-preview" },
lane: {
heightPx: 80, groupId: "ranking-reveals",
@@ -110,12 +177,18 @@ export const rankingStudioAdapters: readonly StudioAdapter[] = [
attachments: [{
id: "reveal", family: "ranking-reveal", tone: "orange-muted", label: "Reveals", icon: "ranking", facet: "visual",
lane: { heightPx: 40 },
- parameters: [
- { name: "label", label: "Label", writable: true },
- { name: "icon", label: "Icon", writable: false },
- { name: "rank", label: "Rank", control: "number", writable: true },
- { name: "preset", label: "Preset", control: "boolean", writable: true },
- { name: "stack", label: "Stack", control: "number", writable: true },
+ bindings: [
+ { name: "label", writable: true },
+ { name: "icon" },
+ { name: "rank", writable: true },
+ { name: "preset", writable: true },
+ { name: "stack", writable: true },
+ ],
+ inspector: [
+ { binding: "label", label: "Label", domain: "how", page: { id: "item", label: "Item" }, section: { id: "item", label: "Item" }, control: "text" },
+ { binding: "rank", label: "Rank", domain: "how", page: { id: "item", label: "Item" }, section: { id: "item", label: "Item" }, control: "number" },
+ { binding: "preset", label: "Preset", domain: "how", page: { id: "item", label: "Item" }, section: { id: "item", label: "Item" }, control: "boolean" },
+ { binding: "stack", label: "Stack", domain: "where", page: { id: "stacking", label: "Stacking" }, section: { id: "stacking", label: "Stacking" }, control: "number" },
],
timelineEdits: selectionWindowTimelineEdits(),
}],
@@ -130,25 +203,37 @@ export const rankingStudioAdapters: readonly StudioAdapter[] = [
output: { type: "VisualTrack", surface, modules: ["@hypit/ranking"] },
family: "ranking", tone: "orange", label, icon: "ranking", requiredValues: ["schedule", "program"],
timelineEdits: selectionWindowTimelineEdits(),
- parameters: [
- ...commonParameters,
+ bindings: [
+ ...commonBindings,
rankingStyle(surface === "tier" ? "tier-style" : "top-three-style"),
- { name: "terminal", label: "Terminal", writable: false },
+ { name: "terminal" },
+ ],
+ inspector: [
+ ...frameInspector,
+ ...rankingInspector(surface === "tier" ? "tier-style" : "top-three-style"),
],
poster: { source: "surface-preview" },
lane: { heightPx: 80, groupId: `${id}-activations` },
attachments: [{
id: "activation", family: "ranking-reveal", tone: "orange-muted", label: "Activations", icon: "ranking", facet: "visual",
lane: { heightPx: 40 },
- parameters: id === "tier" ? [
- { name: "tier", label: "Tier", writable: true },
- { name: "entry", label: "Entry", control: "select", writable: true, options: ["direct", "stage"] },
- { name: "icon", label: "Icon", writable: false },
- { name: "stack", label: "Stack", control: "number", writable: true },
+ bindings: id === "tier" ? [
+ { name: "tier", writable: true },
+ { name: "entry", writable: true },
+ { name: "icon" },
+ { name: "stack", writable: true },
+ ] : [
+ { name: "label", writable: true },
+ { name: "icon" },
+ { name: "stack", writable: true },
+ ],
+ inspector: id === "tier" ? [
+ { binding: "tier", label: "Tier", domain: "how", page: { id: "item", label: "Item" }, section: { id: "item", label: "Item" }, control: "text" },
+ { binding: "entry", label: "Entry", domain: "when", page: { id: "activation", label: "Activation" }, section: { id: "activation", label: "Activation" }, control: "select", options: ["direct", "stage"] },
+ { binding: "stack", label: "Stack", domain: "where", page: { id: "stacking", label: "Stacking" }, section: { id: "stacking", label: "Stacking" }, control: "number" },
] : [
- { name: "label", label: "Label", writable: true },
- { name: "icon", label: "Icon", writable: false },
- { name: "stack", label: "Stack", control: "number", writable: true },
+ { binding: "label", label: "Label", domain: "how", page: { id: "item", label: "Item" }, section: { id: "item", label: "Item" }, control: "text" },
+ { binding: "stack", label: "Stack", domain: "where", page: { id: "stacking", label: "Stacking" }, section: { id: "stacking", label: "Stacking" }, control: "number" },
],
timelineEdits: projectedPointTimelineEdits(),
}],
diff --git a/packages/ranking/README.md b/packages/ranking/README.md
index 9fa43426..50a4cfe7 100644
--- a/packages/ranking/README.md
+++ b/packages/ranking/README.md
@@ -15,6 +15,13 @@ Each `*Style` declaration compiles one SVS Recipe and exact font reference into
plus a private named `.sound` Style output. A Ranking component connects both outputs when authored
sound exists; no sound produces no audio branch.
+Ranking Recipe vocabulary is typed at the domain boundary. `rank-colors` and
+the exactly-three `slot-colors` are color lists; Tier `rows` is a list of
+`{ id, label, color }` records. SVS therefore preserves those values directly
+instead of hiding them in `|`- or `:`-delimited strings. Studio may render the
+same schema as a palette/list through `ranking-studio`, while other editors and
+diagnostic tools can consume it without depending on Studio.
+
Visible author copy may be literal or an ordinary graph `Text` reference. Column and TopThree use
`label={copy}`. When a reference is used, the graph first materializes the package-owned item shell
from that exact Text and then shares the one result across schedule, event and render work. Tier row
diff --git a/packages/ranking/src/manifest.ts b/packages/ranking/src/manifest.ts
index 9f407e81..9c56acfd 100644
--- a/packages/ranking/src/manifest.ts
+++ b/packages/ranking/src/manifest.ts
@@ -80,6 +80,75 @@ const unsigned = { kind: "number", integer: true, minimum: 0 } as const;
const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>, allowUnknown = false): ValueSchema => ({
kind: "object", fields, ...(allowUnknown ? { allowUnknown: true } : {}),
});
+const recipeColor = { kind: "string", format: "color", minLength: 7, maxLength: 9 } as const satisfies ValueSchema;
+const rankingRecipeSchemas = {
+ rows: { kind: "array", minItems: 1, items: object({
+ id: { schema: { kind: "string", minLength: 1 } },
+ label: { schema: { kind: "string", minLength: 1 } },
+ color: { schema: recipeColor },
+ }) },
+ "rank-colors": { kind: "array", minItems: 1, items: recipeColor },
+ "slot-colors": { kind: "array", minItems: 3, maxItems: 3, items: recipeColor },
+ "font-size": { kind: "number", minimum: 0 },
+ "font-weight": { kind: "number", integer: true, minimum: 1 },
+ "text-color": recipeColor,
+ "line-height": { kind: "number", minimum: 0 },
+ "board-background": recipeColor,
+ "board-border-color": recipeColor,
+ "board-border-width": { kind: "number", minimum: 0 },
+ "board-radius": { kind: "number", minimum: 0 },
+ "board-shadow-x": { kind: "number" },
+ "board-shadow-y": { kind: "number" },
+ "board-shadow-blur": { kind: "number", minimum: 0 },
+ "board-shadow-spread": { kind: "number" },
+ "board-shadow-color": recipeColor,
+ "appear-frames": { kind: "number", integer: true, minimum: 0 },
+ "move-frames": { kind: "number", integer: true, minimum: 0 },
+ "motion-easing": { kind: "string", enum: ["linear", "ease-in", "ease-out", "ease-in-out"] },
+ "label-width": { kind: "number", minimum: 0 },
+ padding: { kind: "number", minimum: 0 },
+ "row-height": { kind: "number", minimum: 0 },
+ "row-gap": { kind: "number", minimum: 0 },
+ "cell-gap": { kind: "number", minimum: 0 },
+ "icon-size": { kind: "number", minimum: 0 },
+ "icon-radius": { kind: "number", minimum: 0 },
+ "icon-fit": { kind: "string", enum: ["contain", "cover"] },
+ "stage-x": { kind: "number" },
+ "stage-y": { kind: "number" },
+ "stage-size": { kind: "number", minimum: 0 },
+ "center-x": { kind: "number" },
+ "baseline-y": { kind: "number" },
+ "slot-gap": { kind: "number", minimum: 0 },
+ "ring-width": { kind: "number", minimum: 0 },
+ "label-gap": { kind: "number", minimum: 0 },
+ "board-stack": { kind: "number", integer: true },
+ "stage-stack": { kind: "number", integer: true },
+ "item-stack": { kind: "number", integer: true },
+ "appear-gain": { kind: "number", minimum: 0 },
+ "move-gain": { kind: "number", minimum: 0 },
+ "sound-fade-frames": { kind: "number", integer: true, minimum: 0 },
+} as const satisfies Readonly<Record<string, ValueSchema>>;
+
+function typedRecipeProperties<const T extends readonly {
+ readonly name: string;
+ readonly required: boolean;
+ readonly summary: string;
+ readonly values?: readonly string[];
+ readonly fallback?: import("@hypit/protocol").CanonicalValue;
+}[]>(properties: T) {
+ return properties.map((property) => {
+ const schema = rankingRecipeSchemas[property.name as keyof typeof rankingRecipeSchemas];
+ if (schema === undefined) throw new Error(`Ranking Recipe property ${property.name} has no public schema.`);
+ const fallback = schema.kind === "number" && typeof property.fallback === "string"
+ ? Number(property.fallback)
+ : property.fallback;
+ return {
+ ...property,
+ schema,
+ ...(fallback === undefined ? {} : { fallback }),
+ };
+ });
+}
const variants = { kind: "string", enum: ["tier-board", "column", "top-three"] } as const;
const itemBase = {
id: { schema: string },
@@ -174,9 +243,13 @@ export const rankingMarkupSurfaces = [
summary: "Names this Style so a TierBoard can reference it." },
{ name: "recipe", kind: "reference", required: true, accepts: [svsRecipeType],
summary: "Chooses the Recipe carrying the tier rows, board Paint, row and cell geometry, icon treatment, staging pose and motion.",
- recipe: [
- { name: "rows", required: false, fallback: "s:S:#ef4444|a:A:#f59e0b|b:B:#22c55e|c:C:#3b82f6",
- summary: "Defines the tier rows the board draws, each written `id:label:color` and separated by `|`." },
+ recipe: typedRecipeProperties([
+ { name: "rows", required: false, fallback: [
+ { id: "s", label: "S", color: "#ef4444" },
+ { id: "a", label: "A", color: "#f59e0b" },
+ { id: "b", label: "B", color: "#22c55e" },
+ { id: "c", label: "C", color: "#3b82f6" },
+ ], summary: "Defines the ordered tier rows the board draws, each with an id, label and color." },
{ name: "font-size", required: false, fallback: "28",
summary: "Sets the size in pixels the Item copy is set at." },
{ name: "font-weight", required: false, fallback: "700",
@@ -245,7 +318,7 @@ export const rankingMarkupSurfaces = [
summary: "Sets the gain the move sound is played at." },
{ name: "sound-fade-frames", required: false, fallback: "0",
summary: "Sets how many frames each sound fades in and out over." },
- ] },
+ ]) },
{ name: "font", kind: "reference", required: true,
accepts: [mediaTypes.fontArtifact, mediaTypes.fontStack],
summary: "Chooses the exact face, or a whole stack that already carries its own fallbacks, the board copy is set in." },
@@ -272,9 +345,9 @@ export const rankingMarkupSurfaces = [
summary: "Names this Style so a Column can reference it." },
{ name: "recipe", kind: "reference", required: true, accepts: [svsRecipeType],
summary: "Chooses the Recipe carrying the rank colors, board Paint, row geometry, icon treatment, staging pose and motion.",
- recipe: [
- { name: "rank-colors", required: false, fallback: "#facc15|#d1d5db|#fb923c|#60a5fa|#a78bfa",
- summary: "Defines the color each rank badge is drawn in, separated by `|` and reused in order past the last one." },
+ recipe: typedRecipeProperties([
+ { name: "rank-colors", required: false, fallback: ["#facc15", "#d1d5db", "#fb923c", "#60a5fa", "#a78bfa"],
+ summary: "Defines the ordered colors rank badges use, cycling after the last color." },
{ name: "font-size", required: false, fallback: "28",
summary: "Sets the size in pixels the row copy is set at." },
{ name: "font-weight", required: false, fallback: "700",
@@ -339,7 +412,7 @@ export const rankingMarkupSurfaces = [
summary: "Sets the gain the move sound is played at." },
{ name: "sound-fade-frames", required: false, fallback: "0",
summary: "Sets how many frames each sound fades in and out over." },
- ] },
+ ]) },
{ name: "font", kind: "reference", required: true,
accepts: [mediaTypes.fontArtifact, mediaTypes.fontStack],
summary: "Chooses the exact face, or a whole stack that already carries its own fallbacks, the board copy is set in." },
@@ -365,9 +438,9 @@ export const rankingMarkupSurfaces = [
summary: "Names this Style so a TopThree can reference it." },
{ name: "recipe", kind: "reference", required: true, accepts: [svsRecipeType],
summary: "Chooses the Recipe carrying the slot colors, podium geometry, ring and label spacing, board Paint and motion.",
- recipe: [
- { name: "slot-colors", required: false, fallback: "#facc15|#d1d5db|#fb923c",
- summary: "Defines the color each podium slot is drawn in, separated by `|`, and at least three are required." },
+ recipe: typedRecipeProperties([
+ { name: "slot-colors", required: false, fallback: ["#facc15", "#d1d5db", "#fb923c"],
+ summary: "Defines the three ordered colors used by the three podium slots." },
{ name: "font-size", required: false, fallback: "28",
summary: "Sets the size in pixels the slot copy is set at." },
{ name: "font-weight", required: false, fallback: "700",
@@ -410,7 +483,7 @@ export const rankingMarkupSurfaces = [
summary: "Sets the gain a move sound would be played at, though a podium authors none." },
{ name: "sound-fade-frames", required: false, fallback: "0",
summary: "Sets how many frames each sound fades in and out over." },
- ] },
+ ]) },
{ name: "font", kind: "reference", required: true,
accepts: [mediaTypes.fontArtifact, mediaTypes.fontStack],
summary: "Chooses the exact face, or a whole stack that already carries its own fallbacks, the board copy is set in." },
diff --git a/packages/ranking/src/schedule.ts b/packages/ranking/src/schedule.ts
index beae9a53..c99e74b3 100644
--- a/packages/ranking/src/schedule.ts
+++ b/packages/ranking/src/schedule.ts
@@ -200,7 +200,7 @@ export function assertColumnStyle(value: ColumnStyle): void {
export function assertTopThreeStyle(value: TopThreeStyle): void {
assertCommonStyle(value, "TopThreeStyle");
- assert(value.slotColors.length >= 3, "TopThreeStyle requires three slot colors.");
+ assert(value.slotColors.length === 3, "TopThreeStyle requires exactly three slot colors.");
value.slotColors.forEach((item, index) => color(item, `TopThreeStyle.slotColors.${index}`));
for (const [name, coordinate] of [["centerX", value.centerX], ["baselineY", value.baselineY]] as const) {
assert(Number.isFinite(coordinate) && coordinate >= 0 && coordinate <= 1, `TopThreeStyle.${name} is invalid.`);
diff --git a/packages/ranking/src/style.ts b/packages/ranking/src/style.ts
index 7b16b56d..b1a783c5 100644
--- a/packages/ranking/src/style.ts
+++ b/packages/ranking/src/style.ts
@@ -144,18 +144,34 @@ function sound(recipe: SvsRecipe): RankingSoundStyle {
}
function rowList(recipe: SvsRecipe): TierRowStyle[] {
- const raw = text(recipe, "rows", "s:S:#ef4444|a:A:#f59e0b|b:B:#22c55e|c:C:#3b82f6");
- return raw.split("|").map((item, index) => {
- const [id, label, color] = item.split(":").map((part) => part.trim());
- if (!id || !label || !color) fail(recipe, `rows entry ${index + 1} must be id:label:color.`);
- return { id, label, color };
+ const value = recipe.properties.rows ?? [
+ { id: "s", label: "S", color: "#ef4444" },
+ { id: "a", label: "A", color: "#f59e0b" },
+ { id: "b", label: "B", color: "#22c55e" },
+ { id: "c", label: "C", color: "#3b82f6" },
+ ];
+ if (!Array.isArray(value) || value.length === 0) fail(recipe, "rows must be a non-empty array.");
+ return value.map((item, index) => {
+ if (item === null || Array.isArray(item) || typeof item !== "object") {
+ fail(recipe, `rows entry ${index + 1} must be an object.`);
+ }
+ const { id, label, color } = item;
+ if (typeof id !== "string" || id.trim().length === 0
+ || typeof label !== "string" || label.trim().length === 0
+ || typeof color !== "string" || color.trim().length === 0) {
+ fail(recipe, `rows entry ${index + 1} requires text id, label and color fields.`);
+ }
+ return { id: id.trim(), label: label.trim(), color: color.trim() };
});
}
-function colorList(recipe: SvsRecipe, name: string, fallback: string): string[] {
- const result = text(recipe, name, fallback).split("|").map((value) => value.trim()).filter(Boolean);
- if (result.length === 0) fail(recipe, `${name} is empty.`);
- return result;
+function colorList(recipe: SvsRecipe, name: string, fallback: readonly string[]): string[] {
+ const value = recipe.properties[name] ?? fallback;
+ if (!Array.isArray(value) || value.length === 0) fail(recipe, `${name} must be a non-empty color array.`);
+ return value.map((item, index) => {
+ if (typeof item !== "string" || item.trim().length === 0) fail(recipe, `${name} entry ${index + 1} must be a color.`);
+ return item.trim();
+ });
}
export function decodeTierBoardStyle(
@@ -198,7 +214,7 @@ export function decodeColumnStyle(
board: board(recipe),
text: typography(recipe, fonts),
- rankColors: colorList(recipe, "rank-colors", "#facc15|#d1d5db|#fb923c|#60a5fa|#a78bfa"),
+ rankColors: colorList(recipe, "rank-colors", ["#facc15", "#d1d5db", "#fb923c", "#60a5fa", "#a78bfa"]),
paddingPx: number(recipe, "padding", 18),
rowHeightPx: number(recipe, "row-height", 74),
rowGapPx: number(recipe, "row-gap", 10),
@@ -225,7 +241,7 @@ export function decodeTopThreeStyle(
const style: TopThreeStyle = {
text: typography(recipe, fonts),
- slotColors: colorList(recipe, "slot-colors", "#facc15|#d1d5db|#fb923c"),
+ slotColors: colorList(recipe, "slot-colors", ["#facc15", "#d1d5db", "#fb923c"]),
centerX: number(recipe, "center-x", 0.5),
baselineY: number(recipe, "baseline-y", 0.55),
slotGapPx: number(recipe, "slot-gap", 24),
diff --git a/packages/ranking/test/ranking.test.ts b/packages/ranking/test/ranking.test.ts
index ee0edd10..101cdb9b 100644
--- a/packages/ranking/test/ranking.test.ts
+++ b/packages/ranking/test/ranking.test.ts
@@ -266,20 +266,23 @@ test("RankingSchedule requires one item-owned Moment per Item and distinct chron
test("variant Style decoders reject unknown Recipes and keep exact fonts and independent stacks", () => {
const tier = decodeTierBoardStyle(recipe("ranking.tier", {
- rows: "s:S:#ef4444|a:A:#22c55e", "board-stack": 8, "stage-stack": 20, "item-stack": 31,
+ rows: [{ id: "s", label: "S", color: "#ef4444" }, { id: "a", label: "A", color: "#22c55e" }], "board-stack": 8, "stage-stack": 20, "item-stack": 31,
}), font);
assert.deepEqual(tier.style.rows.map((row) => row.id), ["s", "a"]);
assert.equal(tier.style.text.fonts[0]?.sources[0]?.artifact.digest, font.sources[0]!.artifact.digest);
assert.deepEqual([tier.style.boardStackingOrder, tier.style.stageStackingOrder, tier.style.itemStackingOrder], [8, 20, 31]);
assert.throws(() => decodeColumnStyle(recipe("ranking.column", { "tier-only": 1 }), font), /does not accept/u);
assert.equal(decodeTopThreeStyle(recipe("ranking.top"), font).style.slotColors.length, 3);
+ assert.throws(() => decodeTopThreeStyle(recipe("ranking.top", {
+ "slot-colors": ["#111111", "#222222", "#333333", "#444444"],
+ }), font), /exactly three/u);
});
test("TierBoard owns cumulative direct/stage placement and rejects invalid schedule boundaries", () => {
const owner = header("tier-board", "tiers");
const semantic = [tierSpec("alpha", "s", "stage"), tierSpec("beta", "a")];
const style = decodeTierBoardStyle(recipe("ranking.tier", {
- rows: "s:S:#ef4444|a:A:#22c55e", "appear-frames": 5, "move-frames": 8,
+ rows: [{ id: "s", label: "S", color: "#ef4444" }, { id: "a", label: "A", color: "#22c55e" }], "appear-frames": 5, "move-frames": 8,
}), font).style;
let set = createTierBoardItemSet();
set = appendTierBoardItem(set, semantic[0]!, image("alpha"));
@@ -412,7 +415,7 @@ test("visual and sound event plans share exact phase frames while absent sound s
test("each component owns a distinct event law and repeated lowering is canonical", () => {
const tierOwner = header("tier-board", "tier-events");
const tierItems = [tierSpec("direct", "s"), tierSpec("stage", "a", "stage")];
- const tier = decodeTierBoardStyle(recipe("ranking.tier", { rows: "s:S:#ef4444|a:A:#22c55e" }), font).style;
+ const tier = decodeTierBoardStyle(recipe("ranking.tier", { rows: [{ id: "s", label: "S", color: "#ef4444" }, { id: "a", label: "A", color: "#22c55e" }] }), font).style;
assert.deepEqual(buildTierBoardSoundEvents(schedule(tierOwner, tierItems), tier, specs(tierOwner, tierItems)).events.map((item) => item.kind),
["appear", "appear", "move"]);
@@ -457,7 +460,7 @@ test("all three author Surfaces preserve explicit semantic, spatial, font, image
["copy", inlineReference("copy", textTypes.text, sealText("Dynamic ranking copy"))],
]);
const styleCases = [
- ["tier-style", rankingTypes.tierStyle, decodeTierBoardStyleSurface, { rows: "s:S:#ef4444|a:A:#22c55e" }],
+ ["tier-style", rankingTypes.tierStyle, decodeTierBoardStyleSurface, { rows: [{ id: "s", label: "S", color: "#ef4444" }, { id: "a", label: "A", color: "#22c55e" }] }],
["column-style", rankingTypes.columnStyle, decodeColumnStyleSurface, {}],
["top-style", rankingTypes.topThreeStyle, decodeTopThreeStyleSurface, {}],
] as const;
diff --git a/packages/screen-overlay-studio/src/index.ts b/packages/screen-overlay-studio/src/index.ts
index a861d96c..bb497de2 100644
--- a/packages/screen-overlay-studio/src/index.ts
+++ b/packages/screen-overlay-studio/src/index.ts
@@ -1,5 +1,5 @@
import type { ScreenOverlayProgram } from "@hypit/screen-overlay";
-import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft } from "@hypit/studio-adapter";
+import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft, StudioInspectorFieldDeclaration } from "@hypit/studio-adapter";
import { childEntities, projectedWindowTimelineEdits, requiredSurfaceValue, temporalLineageFor } from "@hypit/studio-adapter";
function projectOverlays(context: StudioAdapterContext): readonly StudioEntityDraft[] {
@@ -26,57 +26,51 @@ function projectOverlays(context: StudioAdapterContext): readonly StudioEntityDr
});
}
+const overlayOptions: Readonly<Record<string, readonly string[]>> = {
+ direction: ["left", "right", "up", "down"],
+ chroma: ["monochrome", "color"],
+};
+
+const overlayNames = [
+ "color", "intensity", "opacity", "attack", "hold", "decay", "center-x", "center-y", "radius-x", "radius-y",
+ "softness", "spacing", "thickness", "angle", "travel", "coverage", "feather", "from", "to", "direction",
+ "width", "bars", "colors", "seed", "amount", "size", "chroma", "motion-rate", "min-size", "max-size",
+ "warmth", "drift", "scan-lines", "z",
+] as const;
+
+function title(name: string): string {
+ return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+
+const overlayGeometry = new Set(["center-x", "center-y", "radius-x", "radius-y", "width", "size", "min-size", "max-size", "z"]);
+const overlayMotion = new Set(["attack", "hold", "decay", "travel", "from", "to", "motion-rate", "drift"]);
+const overlayColor = new Set(["color", "colors"]);
+
+const overlayInspector: readonly StudioInspectorFieldDeclaration[] = overlayNames.map((binding) => {
+ const domain = overlayGeometry.has(binding) ? "where" as const : overlayMotion.has(binding) ? "when" as const : "how" as const;
+ const page = overlayGeometry.has(binding) ? "Geometry" : overlayMotion.has(binding) ? "Motion" : overlayColor.has(binding) ? "Color" : "Effect";
+ const options = overlayOptions[binding];
+ const control = options !== undefined ? "select" as const
+ : binding === "color" ? "color" : binding === "colors" ? "text" : "number";
+ return {
+ binding, label: title(binding), domain,
+ page: { id: page.toLowerCase(), label: page }, section: { id: page.toLowerCase(), label: page },
+ control,
+ ...(options === undefined ? {} : { options }),
+ };
+});
+
export const screenOverlayStudioAdapters: readonly StudioAdapter[] = [
{
id: "track", role: "track",
output: { type: "VisualTrack", surface: "track", modules: ["@hypit/screen-overlay"] },
family: "screen-overlay", tone: "orange", icon: "component",
timelineEdits: projectedWindowTimelineEdits({ start: "start", end: "end", duration: "for" }),
- parameters: [
- { name: "start", label: "Start", writable: true },
- { name: "end", label: "End", writable: true },
- { name: "for", label: "For", writable: true },
- { name: "color", label: "Color", writable: true },
- { name: "intensity", label: "Intensity", control: "number", writable: true },
- { name: "opacity", label: "Opacity", control: "number", writable: true },
- { name: "attack", label: "Attack", control: "number", writable: true, unit: "f" },
- { name: "hold", label: "Hold", control: "number", writable: true, unit: "f" },
- { name: "decay", label: "Decay", control: "number", writable: true, unit: "f" },
- { name: "center-x", label: "Center X", control: "number", writable: true },
- { name: "center-y", label: "Center Y", control: "number", writable: true },
- { name: "radius-x", label: "Radius X", control: "number", writable: true },
- { name: "radius-y", label: "Radius Y", control: "number", writable: true },
- { name: "softness", label: "Softness", control: "number", writable: true },
- { name: "spacing", label: "Spacing", control: "number", writable: true },
- { name: "thickness", label: "Thickness", control: "number", writable: true },
- { name: "angle", label: "Angle", control: "number", writable: true },
- { name: "travel", label: "Travel", control: "number", writable: true },
- { name: "coverage", label: "Coverage", control: "number", writable: true },
- { name: "feather", label: "Feather", control: "number", writable: true },
- { name: "from", label: "From", control: "number", writable: true },
- { name: "to", label: "To", control: "number", writable: true },
- {
- name: "direction", label: "Direction", control: "select", writable: true,
- options: ["left", "right", "up", "down"],
- },
- { name: "width", label: "Width", control: "number", writable: true },
- { name: "bars", label: "Bars", control: "number", writable: true },
- { name: "colors", label: "Colors", writable: true },
- { name: "seed", label: "Seed", control: "number", writable: true },
- { name: "amount", label: "Amount", control: "number", writable: true },
- { name: "size", label: "Size", control: "number", writable: true },
- {
- name: "chroma", label: "Chroma", control: "select", writable: true,
- options: ["monochrome", "color"],
- },
- { name: "motion-rate", label: "Motion rate", control: "number", writable: true },
- { name: "min-size", label: "Minimum size", control: "number", writable: true },
- { name: "max-size", label: "Maximum size", control: "number", writable: true },
- { name: "warmth", label: "Warmth", control: "number", writable: true },
- { name: "drift", label: "Drift", control: "number", writable: true },
- { name: "scan-lines", label: "Scan lines", control: "number", writable: true },
- { name: "z", label: "Stack", control: "number", writable: true },
+ bindings: [
+ { name: "start", writable: true }, { name: "end", writable: true }, { name: "for", writable: true },
+ ...overlayNames.map((name) => ({ name, writable: true })),
],
+ inspector: overlayInspector,
requiredValues: ["program"], project: projectOverlays,
poster: { source: "surface-preview" },
lane: { heightPx: 52 },
diff --git a/packages/speech-track-studio/src/index.ts b/packages/speech-track-studio/src/index.ts
index 9038b6d3..590c81c7 100644
--- a/packages/speech-track-studio/src/index.ts
+++ b/packages/speech-track-studio/src/index.ts
@@ -1,22 +1,41 @@
import { speechTrackMarkupSurfaces } from "@hypit/speech-track";
-import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft, StudioParameterDeclaration, StudioRecipeParameterDeclaration } from "@hypit/studio-adapter";
+import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft, StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-adapter";
import { artifactPreview, previewLayer } from "@hypit/studio-adapter";
-const frameParameters: readonly StudioParameterDeclaration[] = [
- { name: "within", label: "Within", writable: false },
- { name: "left", label: "Left", writable: true },
- { name: "top", label: "Top", writable: true },
- { name: "right", label: "Right", writable: true },
- { name: "bottom", label: "Bottom", writable: true },
- { name: "x", label: "X", writable: true },
- { name: "y", label: "Y", writable: true },
- { name: "width", label: "Width", writable: true },
- { name: "height", label: "Height", writable: true },
+const frameParameters: readonly StudioSourceBindingDeclaration[] = [
+ { name: "within" },
+ ...["left", "top", "right", "bottom", "x", "y", "width", "height"].map((name) => ({ name, writable: true })),
];
-const speechVisualRecipe: readonly StudioRecipeParameterDeclaration[] = (speechTrackMarkupSurfaces[0]
+const speechVisualProperties = (speechTrackMarkupSurfaces[0]
?.vocabulary.attributes.find((attribute) => attribute.name === "visual-appearance")?.recipe ?? [])
- .map((property) => ({ name: property.name, group: "where", section: "fit" }));
+;
+
+function title(name: string): string {
+ return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+
+function valuesFor(property: typeof speechVisualProperties[number]): readonly string[] | undefined {
+ return "values" in property ? property.values : undefined;
+}
+
+const speechInspector: readonly StudioInspectorFieldDeclaration[] = [
+ ...frameParameters.filter(({ writable }) => writable === true).map(({ name }) => ({
+ binding: `visual-frame.${name}`, label: title(name), domain: "where" as const,
+ page: { id: "frame", label: "Frame" }, section: { id: "frame", label: "Frame" }, control: "text" as const,
+ })),
+ ...speechVisualProperties.map((property) => ({
+ binding: `visual-appearance.${property.name}`, label: title(property.name), domain: "where" as const,
+ page: { id: "fit", label: "Fit" }, section: { id: "fit", label: "Fit" },
+ ...(property.summary === undefined ? {} : { summary: property.summary }),
+ control: valuesFor(property) !== undefined ? "select" as const : "number" as const,
+ ...(valuesFor(property) === undefined ? {} : { options: valuesFor(property)! }),
+ })),
+ {
+ binding: "visual-z", label: "Stack", domain: "where", page: { id: "stacking", label: "Stacking" },
+ section: { id: "stacking", label: "Stacking" }, control: "number",
+ },
+];
type SpeechVisualTrack = {
readonly presents?: readonly {
@@ -83,14 +102,15 @@ export const speechTrackStudioAdapters: readonly StudioAdapter[] = [
id: "visual", role: "track",
output: { type: "VisualTrack", surface: "track", modules: ["@hypit/speech-track"] },
family: "speech-visual", tone: "blue", label: "Speech Visual", icon: "video",
- parameters: [
- { name: "visual-frame", label: "Frame", writable: false, referenced: frameParameters },
+ bindings: [
+ { name: "visual-frame", referenced: frameParameters },
{
- name: "visual-appearance", label: "Appearance", writable: false,
- recipe: { parameters: speechVisualRecipe },
+ name: "visual-appearance",
+ recipe: { bindings: speechVisualProperties.map(({ name }) => ({ name })) },
},
- { name: "visual-z", label: "Z", control: "number", writable: true },
+ { name: "visual-z", writable: true },
],
+ inspector: speechInspector,
project: projectSpeechVisual,
lane: { heightPx: 76 },
},
@@ -98,7 +118,7 @@ export const speechTrackStudioAdapters: readonly StudioAdapter[] = [
id: "audio", role: "track",
output: { type: "AudioTrack", surface: "track", modules: ["@hypit/speech-track"] },
family: "speech-audio", tone: "green", label: "Speech Audio", icon: "waveform",
- parameters: [], project: projectSpeechAudio,
+ bindings: [], inspector: [], project: projectSpeechAudio,
lane: { heightPx: 48 },
},
];
diff --git a/packages/studio-adapter/README.md b/packages/studio-adapter/README.md
index 2369e94b..9456a05e 100644
--- a/packages/studio-adapter/README.md
+++ b/packages/studio-adapter/README.md
@@ -14,3 +14,25 @@ A project companion contributes package-local adapter ids through
physical package identity, so executable package code cannot impersonate an
official adapter. Project profiles select those packages explicitly; Studio
does not scan `node_modules` for plugins.
+
+Inspector editing deliberately has two declarations:
+
+- `bindings` names exact author endpoints, including explicit reference paths
+ into authored elements or SVS Recipes. A binding is not visible by itself;
+- `inspector` selects writable bindings and gives them a `where`, `how` or
+ `when` domain, an optional package-owned page, a section and one of Studio's
+ finite controls (`text`, `number`, `boolean`, `select`, `color`, `list` or
+ `record`). A domain Recipe may declare a shared canonical-value schema; the
+ companion chooses its presentation while Studio derives and validates the
+ finite structured control without learning domain syntax.
+
+This keeps source traversal, timeline inverses and editor presentation from
+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`.
+
+Structured controls keep a local draft and commit one complete canonical value.
+Their codec is the author language (`@hypit/svs` for Recipe values), not an
+adapter callback. Companions cannot inject DOM, CSS, parsing code or filesystem
+mutations. Official companions also use explicit field tables: an undeclared
+new domain property fails adapter loading instead of inheriting UI from its name.
diff --git a/packages/studio-adapter/package.json b/packages/studio-adapter/package.json
index 4f015359..0241ab5f 100644
--- a/packages/studio-adapter/package.json
+++ b/packages/studio-adapter/package.json
@@ -8,6 +8,7 @@
".": "./src/index.ts"
},
"dependencies": {
- "@hypit/host": "workspace:*"
+ "@hypit/host": "workspace:*",
+ "@hypit/protocol": "workspace:*"
}
}
diff --git a/packages/studio-adapter/src/index.ts b/packages/studio-adapter/src/index.ts
index 2d8c66ed..af7d7502 100644
--- a/packages/studio-adapter/src/index.ts
+++ b/packages/studio-adapter/src/index.ts
@@ -1,4 +1,5 @@
import type { HostFacet } from "@hypit/host";
+import type { CanonicalValue, ValueSchema } from "@hypit/protocol";
export const studioAdapterHostAbi = "hypit.studio-adapter@1";
@@ -7,6 +8,7 @@ export type Range = { readonly start: number; readonly end: number };
export type StudioTrackFamily = string;
export type StudioIcon =
+ | "brand"
| "captions"
| "component"
| "layers"
@@ -92,70 +94,98 @@ export type StudioTemporalBinding = {
readonly consumers: readonly StudioTemporalConsumer[];
};
-export type StudioParameterControl = "text" | "number" | "boolean" | "select";
+export type StudioParameterControl = "text" | "number" | "boolean" | "select" | "color" | "list" | "record";
export type StudioParameterLanguage = "svml" | "svs" | "svrun";
-/** A real source value that an Inspector may display or edit. */
-export type StudioParameter = {
+/** A real author endpoint. Its existence never implies Inspector visibility. */
+export type StudioSourceBinding = {
readonly id: string;
- /** Adapter vocabulary name; unlike id this is stable across source files. */
+ /** Companion-owned path, stable across source files and projected entities. */
+ readonly binding: string;
+ /** Author vocabulary name at the terminal source element. */
readonly name: string;
- readonly label: string;
- /** Package-owned Inspector page, for example Where / How / When. */
- readonly group?: string;
- /** Package-owned subsection inside the page. */
- readonly section?: string;
- readonly summary?: string;
- readonly control: StudioParameterControl;
- readonly value: string;
+ readonly value: CanonicalValue;
+ /** Public author value structure; absent only for legacy scalar bindings. */
+ readonly schema?: ValueSchema;
readonly language: StudioParameterLanguage;
readonly writable: boolean;
- readonly options?: readonly string[];
- readonly unit?: string;
readonly source: {
readonly path: string;
readonly range: Range;
readonly preimage: string;
+ /** Generic syntax framing used only when an absent author property is first materialized. */
+ readonly prefix?: string;
+ readonly suffix?: string;
};
readonly disabledReason?: string;
};
-/** Adapter-owned allowlist for source parameters exposed by Studio. */
-export type StudioParameterDeclaration = {
- readonly name: string;
- readonly label?: string;
+export type StudioInspectorDomain = "where" | "how" | "when";
+
+export type StudioInspectorPageDeclaration = {
+ readonly id: string;
+ readonly label: string;
+};
+
+export type StudioInspectorSectionDeclaration = {
+ readonly id: string;
+ readonly label: string;
+};
+
+/** One visible, writable field selected from a Companion's source bindings. */
+export type StudioInspectorFieldDeclaration = {
+ readonly binding: string;
+ readonly label: string;
+ readonly domain: StudioInspectorDomain;
+ /** Omit for a domain with one unlabelled page. */
+ readonly page?: StudioInspectorPageDeclaration;
+ readonly section: StudioInspectorSectionDeclaration;
+ readonly summary?: string;
+ /** Omit when the binding's public schema selects the finite Studio control. */
readonly control?: StudioParameterControl;
- readonly writable?: boolean;
readonly options?: readonly string[];
readonly unit?: string;
+};
+
+/** Resolved Inspector DTO. Studio renders it and executes its exact source write. */
+export type StudioInspectorField = Omit<StudioInspectorFieldDeclaration, "control"> & {
+ readonly id: string;
+ readonly control: StudioParameterControl;
+ readonly value: CanonicalValue;
+ readonly schema?: ValueSchema;
+ readonly language: StudioParameterLanguage;
+ readonly source: StudioSourceBinding["source"];
+};
+
+/** Adapter-owned source allowlist. It contains no editor presentation. */
+export type StudioSourceBindingDeclaration = {
+ readonly name: string;
+ readonly writable?: boolean;
+ readonly schema?: ValueSchema;
/** Optional declaration for the authored element named by a reference. */
- readonly referenced?: readonly StudioParameterDeclaration[];
+ readonly referenced?: readonly StudioSourceBindingDeclaration[];
/**
- * Companion-owned presentation and allowlist for the SVS Recipe reached
- * through this reference. Domain manifests still own property semantics;
- * they do not own an editor's pages or grouping.
+ * Companion-owned source allowlist for the SVS Recipe reached through this
+ * reference. Inspector presentation is declared separately.
*/
- readonly recipe?: StudioRecipeReferenceDeclaration;
+ readonly recipe?: StudioRecipeReferenceBindingDeclaration;
};
-/** An explicit reference path from an Inspector input to one SVS Recipe. */
-export type StudioRecipeReferenceDeclaration = {
+/** An explicit reference path from one author input to one SVS Recipe. */
+export type StudioRecipeReferenceBindingDeclaration = {
/** Reference-valued attributes followed on local authored elements, in order. */
readonly through?: readonly string[];
- /** Package-owned allowlist and presentation for properties of the reached Recipe. */
- readonly parameters: readonly StudioRecipeParameterDeclaration[];
+ /** Package-owned source allowlist for properties of the reached Recipe. */
+ readonly bindings: readonly StudioRecipeBindingDeclaration[];
};
-export type StudioRecipeParameterDeclaration = {
+export type StudioRecipeBindingDeclaration = {
readonly name: string;
- readonly label?: string;
- readonly group: string;
- readonly section?: string;
- readonly summary?: string;
- readonly control?: StudioParameterControl;
readonly writable?: boolean;
- readonly options?: readonly string[];
- readonly unit?: string;
+ /** Domain-owned public Recipe value structure, never editor presentation. */
+ readonly schema?: ValueSchema;
+ /** Typed public fallback; Studio writes the property only after the author changes it. */
+ readonly fallback?: CanonicalValue;
};
export type StudioTimelineGesture =
@@ -176,7 +206,7 @@ export type StudioEditSourceRole = "start" | "end" | "duration" | "frame" | "x"
export type StudioEditSource = {
readonly role: StudioEditSourceRole;
- readonly source: StudioParameter["source"];
+ readonly source: StudioSourceBinding["source"];
};
export type StudioSemanticEditTarget =
@@ -439,7 +469,6 @@ export type StudioEntityDraft = {
readonly temporal?: StudioTemporalLineage;
/** Studio-local lane partition; omitted means the root lane. */
readonly lane?: string;
- readonly parameters?: readonly StudioParameter[];
/** Optional per-entity override of the owning lane's declared inverses. */
readonly timelineEdits?: readonly StudioTimelineEditDeclaration[];
};
@@ -477,7 +506,10 @@ export type StudioAdapter = {
/** Same-Surface output values required to project this Track for Studio. */
readonly requiredValues?: readonly string[];
readonly lane?: StudioLaneDescription;
- readonly parameters?: readonly StudioParameterDeclaration[];
+ /** Exact author endpoints required by Inspector fields or timeline inverses. */
+ readonly bindings?: readonly StudioSourceBindingDeclaration[];
+ /** Visible field table. Undeclared bindings remain invisible. */
+ readonly inspector?: readonly StudioInspectorFieldDeclaration[];
/** Exact inverse choices this adapter understands for its entities. */
readonly timelineEdits?: readonly StudioTimelineEditDeclaration[];
readonly project?: (context: StudioAdapterContext) => readonly StudioEntityDraft[];
@@ -533,7 +565,8 @@ export type StudioLaneAttachment = {
readonly icon: StudioIcon;
readonly facet: "visual" | "audio";
readonly lane: StudioLaneDescription;
- readonly parameters?: readonly StudioParameterDeclaration[];
+ readonly bindings?: readonly StudioSourceBindingDeclaration[];
+ readonly inspector?: readonly StudioInspectorFieldDeclaration[];
readonly timelineEdits?: readonly StudioTimelineEditDeclaration[];
};
diff --git a/packages/studio/README.md b/packages/studio/README.md
index f362ba81..5c2e636a 100644
--- a/packages/studio/README.md
+++ b/packages/studio/README.md
@@ -46,14 +46,29 @@ runtime, so the project does not install or lock another copy.
The companion owns what its Track means: matching, required same-Surface values,
entities, lane range, finite chrome, title and ordered text/material layers,
-Inspector parameter grouping and exact timeline inverses. Material layers carry an
+source bindings, Inspector fields and exact timeline inverses. Inspector fields
+select real writable bindings and organize them under the Studio-owned
+`Where / How / When` domains, optional companion-owned pages and sections. A
+source binding is never shown merely because Studio can reach it. Material layers carry an
Artifact digest or Surface identity, never a Studio HTTP URL. Studio always owns
time formatting and transport resolution, so chrome and material cannot hide a
title or its time.
Studio owns session-wide behavior and chrome: adapter selection, collision and
replacement rules, fallback defaults, selection treatment, playback, zoom,
-scrolling and source mutation transport. A companion cannot ship arbitrary DOM
-or CSS into the application.
+scrolling, the finite Inspector control set and source mutation transport. A
+companion cannot ship arbitrary DOM or CSS into the application.
+
+The finite control set includes scalar controls plus generic `list` and flat
+`record` composition. Structured values are validated against the domain-owned
+canonical schema, edited as a local draft, and written atomically through the
+same revisioned `parameter.adjust` operation. Studio contains no Ranking,
+Caption or Media list codec.
+
+Inspector controls are Studio behavior, not browser defaults supplied by a
+companion. Focused controls suspend transport shortcuts; numeric values use
+non-spinning text entry so wheel scrolling cannot mutate Source; selects use
+the Studio menu and keyboard navigation. Values still commit only on an
+explicit change through the normal revisioned mutation path.
Temporal lineage comes from the exact executed graph selected by the Run. Studio indexes the
`TemporalPoint` and `TemporalWindow` records in each Track's dependency closure together with their
diff --git a/packages/studio/src/fallback-adapters.ts b/packages/studio/src/fallback-adapters.ts
index ebbd152a..2234c966 100644
--- a/packages/studio/src/fallback-adapters.ts
+++ b/packages/studio/src/fallback-adapters.ts
@@ -85,7 +85,7 @@ export const fallbackStudioAdapters: readonly StudioAdapter[] = [
{ id: "@hypit/studio#semantic-take", role: "semantic-take", output: { type: "SemanticTake" } },
{
id: "@hypit/studio#semantic-track", role: "semantic-track", output: { type: "SemanticTrack" },
- family: "semantic", tone: "teal", label: "Semantic", icon: "timeline",
+ family: "semantic", tone: "teal", label: "Semantic", icon: "brand",
lane: { heightPx: 45 },
},
{
diff --git a/packages/studio/src/parameter-values.ts b/packages/studio/src/parameter-values.ts
new file mode 100644
index 00000000..bb5a5d03
--- /dev/null
+++ b/packages/studio/src/parameter-values.ts
@@ -0,0 +1,81 @@
+import type { CanonicalValue, ValueSchema } from "@hypit/protocol";
+import { formatSvsValue } from "@hypit/svs";
+
+function fail(path: string, expectation: string): never {
+ throw new Error(`${path} ${expectation}.`);
+}
+
+export function validateParameterValue(value: CanonicalValue, schema: ValueSchema, path: string): void {
+ if (schema.kind === "null") {
+ if (value !== null) fail(path, "expects null");
+ return;
+ }
+ if (schema.kind === "boolean") {
+ if (typeof value !== "boolean") fail(path, "expects true or false");
+ return;
+ }
+ if (schema.kind === "number") {
+ if (typeof value !== "number" || !Number.isFinite(value)) fail(path, "expects a finite number");
+ if (schema.integer === true && !Number.isInteger(value)) fail(path, "expects a whole number");
+ if (schema.minimum !== undefined && value < schema.minimum) fail(path, `must be at least ${schema.minimum}`);
+ if (schema.maximum !== undefined && value > schema.maximum) fail(path, `must be at most ${schema.maximum}`);
+ return;
+ }
+ if (schema.kind === "string") {
+ if (typeof value !== "string") fail(path, "expects text");
+ if (schema.enum !== undefined && !schema.enum.includes(value)) fail(path, `does not accept ${value}`);
+ if (schema.minLength !== undefined && value.length < schema.minLength) fail(path, "is too short");
+ if (schema.maxLength !== undefined && value.length > schema.maxLength) fail(path, "is too long");
+ if (schema.format === "color" && !/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(value)) {
+ fail(path, "expects #RRGGBB or #RRGGBBAA");
+ }
+ return;
+ }
+ if (schema.kind === "literal") {
+ if (JSON.stringify(value) !== JSON.stringify(schema.value)) fail(path, "does not match its required literal");
+ return;
+ }
+ if (schema.kind === "array") {
+ if (!Array.isArray(value)) fail(path, "expects a list");
+ if (schema.minItems !== undefined && value.length < schema.minItems) fail(path, `requires at least ${schema.minItems} items`);
+ if (schema.maxItems !== undefined && value.length > schema.maxItems) fail(path, `accepts at most ${schema.maxItems} items`);
+ value.forEach((item, index) => validateParameterValue(item, schema.items, `${path}[${index}]`));
+ return;
+ }
+ if (schema.kind === "object") {
+ if (value === null || Array.isArray(value) || typeof value !== "object") fail(path, "expects a record");
+ const record = value as Readonly<Record<string, CanonicalValue>>;
+ for (const [name, field] of Object.entries(schema.fields)) {
+ const held = record[name];
+ if (held === undefined) {
+ if (field.optional !== true) fail(`${path}.${name}`, "is required");
+ } else {
+ validateParameterValue(held, field.schema, `${path}.${name}`);
+ }
+ }
+ if (schema.allowUnknown !== true) {
+ const unknown = Object.keys(record).find((name) => schema.fields[name] === undefined);
+ if (unknown !== undefined) fail(`${path}.${unknown}`, "is not declared");
+ }
+ return;
+ }
+ if (schema.kind === "oneOf") {
+ const accepted = schema.variants.some((variant) => {
+ try {
+ validateParameterValue(value, variant, path);
+ return true;
+ } catch {
+ return false;
+ }
+ });
+ if (!accepted) fail(path, "does not match an accepted value shape");
+ return;
+ }
+ fail(path, "cannot edit blob values");
+}
+
+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);
+ 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 e873e8cb..ed2844b6 100644
--- a/packages/studio/src/parameters.ts
+++ b/packages/studio/src/parameters.ts
@@ -1,9 +1,12 @@
import { dirname, isAbsolute, relative, resolve } from "node:path";
import type {
- StudioParameter,
- StudioParameterDeclaration,
- StudioRecipeReferenceDeclaration,
+ StudioInspectorField,
+ StudioInspectorFieldDeclaration,
+ StudioSourceBinding,
+ StudioSourceBindingDeclaration,
+ StudioParameterControl,
+ StudioRecipeReferenceBindingDeclaration,
StudioEntityDraft,
StudioPlacement,
StudioEditHandle,
@@ -11,7 +14,6 @@ import type {
StudioTemporalLineage,
StudioTimelineEditDeclaration,
} from "@hypit/studio-adapter";
-import type { MarkupSurfaceRegistryLike, SurfaceRecipePropertyVocabulary } from "@hypit/markup";
import { parseSvs } from "@hypit/svs";
import type { Range } from "./shared.js";
@@ -116,29 +118,20 @@ function recipeParameters(input: {
readonly referenceName: string;
readonly referencePath: string;
readonly placements: readonly Placement[];
- readonly surfaces?: MarkupSurfaceRegistryLike;
- readonly vocabulary?: readonly SurfaceRecipePropertyVocabulary[];
- readonly recipe: StudioRecipeReferenceDeclaration;
+ readonly recipe: StudioRecipeReferenceBindingDeclaration;
readonly through: readonly string[];
-}): readonly StudioParameter[] {
+}): readonly StudioSourceBinding[] {
const [attribute, ...remaining] = input.through;
if (attribute !== undefined) {
const local = input.placements.find((candidate) => candidate.id === input.referencePath);
if (local === undefined) return [];
const referencePath = local.referenceAttributes[attribute];
if (referencePath === undefined || referencePath === input.referencePath) return [];
- const vocabulary = input.surfaces
- ?.resolve(local.module, local.surface)
- ?.vocabulary?.attributes
- .find((candidate) => candidate.name === attribute)
- ?.recipe;
- const selectedVocabulary = vocabulary ?? input.vocabulary;
return recipeParameters({
...input,
current: sourceFor(input.root, local.sourcePath, input.files) ?? input.current,
referencePath,
through: remaining,
- ...(selectedVocabulary === undefined ? {} : { vocabulary: selectedVocabulary }),
});
}
const [alias, ...parts] = input.referencePath.split(".");
@@ -151,38 +144,51 @@ function recipeParameters(input: {
const parsed = parseSvs(source.path, svsText(source.text));
const recipe = parsed.recipes.find((item) => item.value.path === recipePath);
if (recipe === undefined) return [];
- return recipe.properties.flatMap((property): readonly StudioParameter[] => {
- const presentation = input.recipe.parameters.find((candidate) => candidate.name === property.name);
- if (presentation === undefined) return [];
- const declaration = input.vocabulary?.find((candidate) => candidate.name === property.name);
+ return input.recipe.bindings.flatMap((declaration): readonly StudioSourceBinding[] => {
+ const property = recipe.properties.find((candidate) => candidate.name === declaration.name);
+ if (property === undefined) {
+ if (declaration.fallback === undefined) return [];
+ const close = recipe.range.end - 1;
+ const lineStart = Math.max(source.text.lastIndexOf("\n", close - 1), source.text.lastIndexOf("\r", close - 1)) + 1;
+ const closeIndent = source.text.slice(lineStart, close);
+ const multiline = closeIndent.trim().length === 0;
+ const first = recipe.properties[0];
+ const propertyIndent = first === undefined ? `${closeIndent} ` : (() => {
+ const start = Math.max(source.text.lastIndexOf("\n", first.range.start - 1), source.text.lastIndexOf("\r", first.range.start - 1)) + 1;
+ return /^\s*/u.exec(source.text.slice(start, first.range.start))?.[0] ?? `${closeIndent} `;
+ })();
+ return [{
+ id: `${input.draft.id}:${input.referenceName}:${declaration.name}`,
+ binding: `${input.referenceName}.${declaration.name}`,
+ name: declaration.name,
+ value: declaration.fallback,
+ ...(declaration.schema === undefined ? {} : { schema: declaration.schema }),
+ language: "svs" as const,
+ writable: declaration.writable ?? true,
+ source: {
+ path: relative(input.root, sourceAbsolute(input.root, source.path)),
+ range: { start: multiline ? lineStart : close, end: multiline ? lineStart : close },
+ preimage: "",
+ prefix: multiline ? `${propertyIndent}${declaration.name}: ` : ` ${declaration.name}: `,
+ suffix: multiline ? ";\n" : "; ",
+ },
+ } satisfies StudioSourceBinding];
+ }
const preimage = source.text.slice(property.valueRange.start, property.valueRange.end);
- const raw = preimage.trim();
- const options = presentation?.options ?? declaration?.values;
- const summary = presentation?.summary ?? declaration?.summary;
- const control = presentation?.control ?? (options !== undefined
- ? "select" as const
- : raw === "true" || raw === "false"
- ? "boolean" as const
- : /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/u.test(raw) ? "number" as const : "text" as const);
return [{
- id: `${input.draft.id}:${input.referenceName}:${property.name}`,
- name: property.name,
- label: presentation?.label ?? (declaration === undefined ? `${input.referenceName} · ${property.name}` : property.name),
- ...(presentation?.group === undefined ? {} : { group: presentation.group }),
- ...(presentation?.section === undefined ? {} : { section: presentation.section }),
- ...(summary === undefined ? {} : { summary }),
- control,
- value: raw,
+ id: `${input.draft.id}:${input.referenceName}:${declaration.name}`,
+ binding: `${input.referenceName}.${declaration.name}`,
+ name: declaration.name,
+ value: recipe.value.properties[declaration.name] ?? preimage.trim(),
+ ...(declaration.schema === undefined ? {} : { schema: declaration.schema }),
language: "svs" as const,
- writable: presentation?.writable ?? true,
- ...(options === undefined ? {} : { options }),
- ...(presentation?.unit === undefined ? {} : { unit: presentation.unit }),
+ writable: declaration.writable ?? true,
source: {
path: relative(input.root, sourceAbsolute(input.root, source.path)),
range: property.valueRange,
preimage,
},
- } satisfies StudioParameter];
+ } satisfies StudioSourceBinding];
});
}
@@ -192,9 +198,9 @@ function referencedParameters(input: {
readonly draft: StudioEntityDraft;
readonly referenceName: string;
readonly referencePath: string;
- readonly declarations: readonly StudioParameterDeclaration[];
+ readonly declarations: readonly StudioSourceBindingDeclaration[];
readonly placements: readonly Placement[];
-}): readonly StudioParameter[] {
+}): readonly StudioSourceBinding[] {
const targetId = input.referencePath;
const target = authoredElements(input.placements).find((candidate) => candidate.id === targetId);
if (target === undefined) return [];
@@ -209,14 +215,12 @@ function referencedParameters(input: {
const writable = declaration.writable === true && reference === undefined;
return [{
id: `${input.draft.id}:${input.referenceName}:${targetId}:${declaration.name}`,
+ binding: `${input.referenceName}.${declaration.name}`,
name: declaration.name,
- label: `${input.referenceName} · ${declaration.label ?? declaration.name}`,
- control: declaration.control ?? "text",
value,
+ ...(declaration.schema === undefined ? {} : { schema: declaration.schema }),
language: languageOf(target.sourcePath),
writable,
- ...(declaration.options === undefined ? {} : { options: declaration.options }),
- ...(declaration.unit === undefined ? {} : { unit: declaration.unit }),
source: {
path: relative(input.root, sourceAbsolute(input.root, target.sourcePath)),
range,
@@ -225,7 +229,7 @@ function referencedParameters(input: {
...(!writable
? { disabledReason: reference === undefined ? "该几何值由组件声明为只读。" : "引用由作者在 SVML 中绑定,面板不替换引用关系。" }
: {}),
- } satisfies StudioParameter];
+ } satisfies StudioSourceBinding];
});
}
@@ -234,15 +238,14 @@ function referencedParameters(input: {
* still discovered by the generic markup frontend, while the meaning and
* editability remain package-owned Studio ABI data.
*/
-export function parametersForDraft(input: {
+export function sourceBindingsForDraft(input: {
readonly root: string;
readonly files: readonly StudioSourceFile[];
readonly placement: StudioPlacement | undefined;
readonly draft: StudioEntityDraft;
- readonly declarations: readonly StudioParameterDeclaration[];
+ readonly declarations: readonly StudioSourceBindingDeclaration[];
readonly placements?: readonly Placement[];
- readonly surfaces?: MarkupSurfaceRegistryLike;
-}): readonly StudioParameter[] {
+}): readonly StudioSourceBinding[] {
const placement = input.placement;
if (placement === undefined || input.declarations.length === 0) return [];
const element = elementFor(placement, input.draft);
@@ -263,14 +266,12 @@ export function parametersForDraft(input: {
const writable = declaration.writable === true && !isReference;
return [{
id: `${input.draft.id}:${name}`,
+ binding: name,
name,
- label: declaration.label ?? name,
- control: declaration.control ?? "text",
value,
+ ...(declaration.schema === undefined ? {} : { schema: declaration.schema }),
language: languageOf(element.sourcePath),
writable,
- ...(declaration.options === undefined ? {} : { options: declaration.options }),
- ...(declaration.unit === undefined ? {} : { unit: declaration.unit }),
source: {
path: relative(input.root, sourceAbsolute(input.root, element.sourcePath)),
range,
@@ -279,7 +280,7 @@ export function parametersForDraft(input: {
...(!writable
? { disabledReason: isReference ? "引用由作者在 SVML 中绑定,面板不替换引用关系。" : "该参数由组件声明为只读。" }
: {}),
- } satisfies StudioParameter];
+ } satisfies StudioSourceBinding];
});
const recipes = input.declarations.flatMap((declaration) => {
const referencePath = input.draft.parameterReferences?.[declaration.name]
@@ -291,7 +292,7 @@ export function parametersForDraft(input: {
root: input.root,
files: input.files,
draft: input.draft,
- referenceName: declaration.label ?? declaration.name,
+ referenceName: declaration.name,
referencePath,
declarations: declaration.referenced,
placements: input.placements ?? [],
@@ -303,10 +304,9 @@ export function parametersForDraft(input: {
files: input.files,
current: file,
draft: input.draft,
- referenceName: declaration.label ?? declaration.name,
+ referenceName: declaration.name,
referencePath,
placements: input.placements ?? [],
- ...(input.surfaces === undefined ? {} : { surfaces: input.surfaces }),
recipe: declaration.recipe,
through: declaration.recipe.through ?? [],
});
@@ -315,6 +315,48 @@ export function parametersForDraft(input: {
return [...direct, ...recipes];
}
+function controlForSchema(schema: StudioSourceBinding["schema"]): StudioParameterControl | undefined {
+ if (schema === undefined) return undefined;
+ if (schema.kind === "boolean") return "boolean";
+ if (schema.kind === "number") return "number";
+ if (schema.kind === "string") return schema.enum === undefined
+ ? schema.format === "color" ? "color" : "text"
+ : "select";
+ if (schema.kind === "array") return "list";
+ if (schema.kind === "object") return "record";
+ return undefined;
+}
+
+/** Resolve the Companion's visible field table against real writable bindings. */
+export function inspectorFieldsForBindings(
+ draft: StudioEntityDraft,
+ bindings: readonly StudioSourceBinding[],
+ declarations: readonly StudioInspectorFieldDeclaration[],
+): readonly StudioInspectorField[] {
+ const byBinding = new Map(bindings.map((binding) => [binding.binding, binding] as const));
+ return declarations.flatMap((declaration): readonly StudioInspectorField[] => {
+ const binding = byBinding.get(declaration.binding);
+ if (binding === undefined || !binding.writable) return [];
+ const control = declaration.control ?? controlForSchema(binding.schema);
+ if (control === undefined) {
+ throw new Error(`Studio Inspector binding ${declaration.binding} has neither a control nor a supported public schema.`);
+ }
+ const schemaOptions = binding.schema?.kind === "string" ? binding.schema.enum : undefined;
+ return [{
+ ...declaration,
+ id: `${draft.id}:inspector:${declaration.binding}`,
+ control,
+ value: binding.value,
+ ...(binding.schema === undefined ? {} : { schema: binding.schema }),
+ ...(declaration.options !== undefined || schemaOptions === undefined
+ ? {}
+ : { options: schemaOptions }),
+ language: binding.language,
+ source: binding.source,
+ }];
+ });
+}
+
const ABSOLUTE_DURATION = /^\s*\d+(?:\.\d+)?(?:f|ms|s)\s*$/u;
/**
@@ -325,20 +367,20 @@ const ABSOLUTE_DURATION = /^\s*\d+(?:\.\d+)?(?:f|ms|s)\s*$/u;
* until their package declares an unambiguous inverse.
*/
export function resolveTimelineEditHandles(
- parameters: readonly StudioParameter[],
+ bindings: readonly StudioSourceBinding[],
declarations: readonly StudioTimelineEditDeclaration[],
temporal?: StudioTemporalLineage,
semantic?: StudioSemanticTimeline,
): readonly StudioEditHandle[] {
- const byName = new Map<string, StudioParameter>();
- for (const parameter of parameters) {
+ const byName = new Map<string, StudioSourceBinding>();
+ for (const binding of bindings) {
// Timing source attributes live in SVML. A nested Recipe may legitimately
// also have a property named `start`; it must never shadow the author
// window when a clip is being dragged.
- if (parameter.language === "svml" && !byName.has(parameter.name)) byName.set(parameter.name, parameter);
+ if (binding.language === "svml" && !byName.has(binding.binding)) byName.set(binding.binding, binding);
}
- const absolute = (parameter: StudioParameter | undefined): parameter is StudioParameter =>
- parameter !== undefined && parameter.writable && ABSOLUTE_DURATION.test(parameter.value);
+ const absolute = (binding: StudioSourceBinding | undefined): binding is StudioSourceBinding =>
+ binding !== undefined && binding.writable && typeof binding.value === "string" && ABSOLUTE_DURATION.test(binding.value);
const disabled = (gesture: StudioTimelineEditDeclaration["gesture"], reason: string): StudioEditHandle => ({
id: `timeline.adjust:${gesture}`,
operation: "timeline.adjust",
diff --git a/packages/studio/src/server.ts b/packages/studio/src/server.ts
index 3f8545df..0ff885c0 100644
--- a/packages/studio/src/server.ts
+++ b/packages/studio/src/server.ts
@@ -12,6 +12,7 @@ import type { ServedFile } from "./compile.js";
import type { StudioDomain } from "./domain.js";
import type { StudioAdapterRegistry } from "./studio-registry.js";
import { loadStudioRun } from "./run.js";
+import { serializeParameterValue, validateParameterValue } from "./parameter-values.js";
import { readStudioSession } from "./session.js";
import type { Range, StudioFailure, StudioLibraryView, StudioMutation, StudioSnapshot } from "./shared.js";
import { createStudioStoryboard } from "./storyboard.js";
@@ -314,22 +315,28 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
const mutationPatches = async (mutation: StudioMutation): Promise<readonly Patch[]> => {
if (mutation.type === "timeline.adjust") return timelinePatches(mutation);
const clip = currentClip(mutation.entityId);
- const parameter = clip.parameters.find((candidate) => candidate.id === mutation.parameterId);
- if (parameter === undefined || !parameter.writable) {
+ const parameter = clip.inspector.find((candidate) => candidate.id === mutation.parameterId);
+ if (parameter === undefined) {
throw new Error(`Entity ${mutation.entityId} has no writable parameter ${mutation.parameterId}.`);
}
- if (parameter.control === "boolean" && mutation.value !== "true" && mutation.value !== "false") {
+ if (parameter.schema !== undefined) {
+ validateParameterValue(mutation.value, parameter.schema, parameter.label);
+ } else if (parameter.control === "boolean" && typeof mutation.value !== "boolean") {
throw new Error(`${parameter.label} expects true or false.`);
- }
- if (parameter.control === "number" && !Number.isFinite(Number(mutation.value))) {
+ } 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")
+ && typeof mutation.value !== "string") {
+ throw new Error(`${parameter.label} expects text.`);
}
- if (parameter.options !== undefined && !parameter.options.includes(mutation.value)) {
+ if (parameter.options !== undefined && (typeof mutation.value !== "string" || !parameter.options.includes(mutation.value))) {
throw new Error(`${parameter.label} does not accept ${mutation.value}.`);
}
- return mutation.value === parameter.source.preimage ? [] : [{
+ const encoded = serializeParameterValue(mutation.value, parameter.language);
+ const replacement = `${parameter.source.prefix ?? ""}${encoded}${parameter.source.suffix ?? ""}`;
+ return replacement === parameter.source.preimage ? [] : [{
...parameter.source,
- replacement: mutation.value,
+ replacement,
}];
};
@@ -430,7 +437,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
return;
}
if (body.type === "parameter.adjust"
- && (typeof body.parameterId !== "string" || typeof body.value !== "string")) {
+ && (typeof body.parameterId !== "string" || body.value === undefined)) {
json(response, 400, { error: "Expected a parameter identity and value." });
return;
}
diff --git a/packages/studio/src/shared.ts b/packages/studio/src/shared.ts
index 8a7e2b8a..fe88e6f3 100644
--- a/packages/studio/src/shared.ts
+++ b/packages/studio/src/shared.ts
@@ -10,7 +10,8 @@ import type {
StudioEditHandle,
StudioLaneDescription,
StudioMaterialPreview,
- StudioParameter,
+ StudioInspectorField,
+ StudioInspectorDomain,
StudioSemanticAnchor,
StudioSemanticSegment,
StudioSemanticTimeline,
@@ -24,6 +25,7 @@ import type {
StudioTimelineTone,
StudioTrackFamily,
} from "@hypit/studio-adapter";
+import type { CanonicalValue } from "@hypit/protocol";
export type {
Range,
@@ -32,7 +34,8 @@ export type {
StudioEditHandle,
StudioLaneDescription,
StudioMaterialPreview,
- StudioParameter,
+ StudioInspectorField,
+ StudioInspectorDomain,
StudioTemporalLineage,
StudioTemporalPhase,
StudioTemporalProjection,
@@ -104,7 +107,8 @@ export type Clip = {
readonly temporal?: StudioTemporalLineage;
/** Rendering identities implementing this author entity; optional for non-visual entities. */
readonly renderIds: readonly string[];
- readonly parameters: readonly StudioParameter[];
+ /** Companion-selected writable fields; hidden source bindings never cross into this surface. */
+ readonly inspector: readonly StudioInspectorField[];
readonly editHandles: readonly StudioEditHandle[];
};
@@ -294,7 +298,7 @@ export type StudioMutation =
readonly revision: number;
readonly entityId: string;
readonly parameterId: string;
- readonly value: string;
+ readonly value: CanonicalValue;
};
export type StudioFailure = {
diff --git a/packages/studio/src/snapshot.ts b/packages/studio/src/snapshot.ts
index 084c7a52..82d40f6c 100644
--- a/packages/studio/src/snapshot.ts
+++ b/packages/studio/src/snapshot.ts
@@ -26,7 +26,7 @@ import {
} from "./studio-registry.js";
import type { StudioAdapterRegistry } from "./studio-registry.js";
import type { StudioEntityDraft } from "./studio-registry.js";
-import { parametersForDraft, resolveTimelineEditHandles } from "./parameters.js";
+import { inspectorFieldsForBindings, resolveTimelineEditHandles, sourceBindingsForDraft } from "./parameters.js";
import type { StudioSourceFile } from "./parameters.js";
type Present = {
@@ -322,29 +322,34 @@ export function snapshot(registry: StudioAdapterRegistry, built: Preview, input:
semantic,
generic,
}).map((draft) => {
- const parameters = parametersForDraft({
+ const bindings = sourceBindingsForDraft({
root: input.workspaceRoot,
files: input.sourceFiles,
placement,
draft,
- declarations: registry.parameterDeclarations(item, placement, draft.lane),
+ declarations: registry.bindingDeclarations(item, placement, draft.lane),
placements: built.source.observations.placements,
- surfaces: input.surfaces,
});
+ const inspector = inspectorFieldsForBindings(
+ draft,
+ bindings,
+ registry.inspectorDeclarations(item, placement, draft.lane),
+ );
const editHandles = resolveTimelineEditHandles(
- parameters,
+ bindings,
draft.timelineEdits ?? registry.timelineEdits(item, placement, draft.lane),
draft.temporal,
semantic,
);
return {
- draft: parameters.length === 0 ? draft : { ...draft, parameters },
+ draft,
+ inspector,
editHandles,
};
});
const clips: Clip[] = drafts
.filter(({ draft }) => draft.lane === undefined)
- .map(({ draft, editHandles }) => sealStudioClip(item.outputRef, draft, binding, editHandles));
+ .map(({ draft, inspector, editHandles }) => sealStudioClip(item.outputRef, draft, binding, editHandles, inspector));
const provenance: CandidateProvenance = {
output: item.name,
outputRef: item.outputRef,
@@ -368,8 +373,8 @@ export function snapshot(registry: StudioAdapterRegistry, built: Preview, input:
id: `${item.outputRef}::studio::${attachment.attachmentId}`,
label: attachment.label ?? attachment.attachmentId ?? item.name,
row: 0,
- clips: attachedDrafts.map(({ draft, editHandles }) =>
- sealStudioClip(item.outputRef, draft, attachment, editHandles)),
+ clips: attachedDrafts.map(({ draft, inspector, editHandles }) =>
+ sealStudioClip(item.outputRef, draft, attachment, editHandles, inspector)),
binding: attachment,
provenance,
});
diff --git a/packages/studio/src/studio-registry.ts b/packages/studio/src/studio-registry.ts
index 3c2246c1..d3b8b45a 100644
--- a/packages/studio/src/studio-registry.ts
+++ b/packages/studio/src/studio-registry.ts
@@ -6,6 +6,7 @@ import type {
StudioLaneAttachment,
StudioProjectionRole,
StudioResolvedTrack,
+ StudioSourceBindingDeclaration,
StudioSpan,
StudioTimelineEditDeclaration,
} from "@hypit/studio-adapter";
@@ -20,9 +21,46 @@ const flatLane = {
};
const tones = new Set(["blue", "green", "teal", "violet", "magenta", "orange", "orange-muted", "neutral"]);
-const icons = new Set(["captions", "component", "layers", "ranking", "text", "timeline", "video", "waveform"]);
+const icons = new Set(["brand", "captions", "component", "layers", "ranking", "text", "timeline", "video", "waveform"]);
const chromes = new Set(["standard", "group", "point"]);
const layouts = new Set(["repeat-x", "cover", "contain", "storyboard", "waveform"]);
+const inspectorDomains = new Set(["where", "how", "when"]);
+const inspectorControls = new Set(["text", "number", "boolean", "select", "color"]);
+
+function bindingPaths(declarations: readonly StudioSourceBindingDeclaration[], prefix = ""): Set<string> {
+ const paths = new Set<string>();
+ for (const declaration of declarations) {
+ const path = prefix.length === 0 ? declaration.name : `${prefix}.${declaration.name}`;
+ paths.add(path);
+ for (const nested of bindingPaths(declaration.referenced ?? [], path)) paths.add(nested);
+ for (const recipe of declaration.recipe?.bindings ?? []) paths.add(`${path}.${recipe.name}`);
+ }
+ return paths;
+}
+
+function validateInspector(
+ subject: string,
+ bindings: readonly StudioSourceBindingDeclaration[] | undefined,
+ fields: StudioAdapter["inspector"],
+): void {
+ const paths = bindingPaths(bindings ?? []);
+ const seen = new Set<string>();
+ for (const field of fields ?? []) {
+ if (seen.has(field.binding)) throw new Error(`${subject} repeats Inspector field ${field.binding}`);
+ seen.add(field.binding);
+ if (!paths.has(field.binding)) throw new Error(`${subject} Inspector field ${field.binding} has no source binding`);
+ if (!inspectorDomains.has(field.domain)) throw new Error(`${subject} selects unsupported Inspector domain ${field.domain}`);
+ if (field.control !== undefined && !inspectorControls.has(field.control)) {
+ throw new Error(`${subject} selects unsupported Inspector control ${field.control}`);
+ }
+ if (field.label.trim().length === 0 || field.section.id.length === 0 || field.section.label.trim().length === 0) {
+ throw new Error(`${subject} Inspector field ${field.binding} has incomplete presentation`);
+ }
+ if (field.control === "select" && (field.options === undefined || field.options.length === 0)) {
+ throw new Error(`${subject} Inspector field ${field.binding} has no select options`);
+ }
+ }
+}
function validateTimelineEdits(subject: string, edits: readonly StudioTimelineEditDeclaration[] | undefined): void {
const gestures = new Set<string>();
@@ -53,6 +91,7 @@ function validateAdapterVocabulary(adapter: StudioAdapter): void {
if (adapter.icon !== undefined && !icons.has(adapter.icon)) {
throw new Error(`Studio adapter ${adapter.id} selects unsupported icon ${adapter.icon}`);
}
+ validateInspector(`Studio adapter ${adapter.id}`, adapter.bindings, adapter.inspector);
validateTimelineEdits(`Studio adapter ${adapter.id}`, adapter.timelineEdits);
for (const attachment of adapter.attachments ?? []) {
if (attachment.tone !== undefined && !tones.has(attachment.tone)) {
@@ -61,6 +100,7 @@ function validateAdapterVocabulary(adapter: StudioAdapter): void {
if (!icons.has(attachment.icon)) {
throw new Error(`Studio adapter ${adapter.id} attachment ${attachment.id} selects unsupported icon ${attachment.icon}`);
}
+ validateInspector(`Studio adapter ${adapter.id} attachment ${attachment.id}`, attachment.bindings, attachment.inspector);
validateTimelineEdits(`Studio adapter ${adapter.id} attachment ${attachment.id}`, attachment.timelineEdits);
}
}
@@ -191,7 +231,7 @@ export class StudioAdapterRegistry {
...(authoredLabel === undefined
? (adapter?.label === undefined ? {} : { label: adapter.label })
: { label: authoredLabel }),
- icon: adapter?.icon ?? "timeline",
+ icon: adapter?.icon ?? "brand",
lane: adapter?.lane ?? flatLane,
};
}
@@ -271,16 +311,28 @@ export class StudioAdapterRegistry {
return projected;
}
- parameterDeclarations(
+ bindingDeclarations(
+ track: StudioResolvedTrack,
+ placement: Placement | undefined,
+ lane?: string,
+ ) {
+ const adapter = this.#trackAdapter(track);
+ if (lane !== undefined) {
+ return adapter.attachments?.find((attachment) => attachment.id === lane)?.bindings ?? [];
+ }
+ return adapter.bindings ?? [];
+ }
+
+ inspectorDeclarations(
track: StudioResolvedTrack,
placement: Placement | undefined,
lane?: string,
) {
const adapter = this.#trackAdapter(track);
if (lane !== undefined) {
- return adapter.attachments?.find((attachment) => attachment.id === lane)?.parameters ?? [];
+ return adapter.attachments?.find((attachment) => attachment.id === lane)?.inspector ?? [];
}
- return adapter.parameters ?? [];
+ return adapter.inspector ?? [];
}
timelineEdits(
@@ -301,6 +353,7 @@ export function sealStudioClip(
draft: StudioEntityDraft,
fallback: StudioTrackBinding,
editHandles: readonly StudioEditHandle[] = [],
+ inspector: Clip["inspector"] = [],
): Clip {
return {
id: draft.id.startsWith(`${outputRef}:`) ? draft.id : `${outputRef}:${draft.id}`,
@@ -317,7 +370,7 @@ export function sealStudioClip(
chrome: "standard",
},
...(draft.temporal === undefined ? {} : { temporal: draft.temporal }),
- parameters: draft.parameters ?? [],
+ inspector,
editHandles,
renderIds: draft.renderIds ?? (draft.presentId === undefined ? [] : [draft.presentId]),
};
diff --git a/packages/studio/src/style.css b/packages/studio/src/style.css
index 9b734f0b..c4147795 100644
--- a/packages/studio/src/style.css
+++ b/packages/studio/src/style.css
@@ -225,57 +225,43 @@ button:focus-visible, textarea:focus-visible {
/* Source */
.library { height: 100%; min-width: 0; min-height: 0; display: flex; flex-direction: column; background: var(--panel); }
.library-tabs {
- height: 58px;
+ height: 36px;
flex: none;
- display: grid;
- grid-template-columns: repeat(3, minmax(0, 1fr));
+ display: flex;
align-items: stretch;
+ justify-content: flex-start;
+ gap: 18px;
+ padding: 0 10px;
border-bottom: 1px solid var(--line);
- background: #17181b;
+ background: var(--panel);
}
.library-tab {
position: relative;
min-width: 0;
display: flex;
- flex-direction: column;
+ flex-direction: row;
align-items: center;
justify-content: center;
- gap: 3px;
- padding: 5px 8px 4px;
+ gap: 7px;
+ padding: 0 2px;
border: 0;
background: transparent;
- color: #858991;
- transition: color 120ms ease, background 120ms ease;
+ color: var(--text-2);
}
-.library-tab:hover { color: #c6c9cf; background: rgba(255, 255, 255, .018); }
.library-tab.active { color: var(--interaction-accent); }
.library-tab.active::after {
content: "";
position: absolute;
- right: 22%;
+ right: 0;
bottom: -1px;
- left: 22%;
+ left: 0;
height: 2px;
border-radius: 2px 2px 0 0;
background: var(--interaction-accent);
box-shadow: 0 -3px 12px color-mix(in srgb, var(--interaction-accent) 28%, transparent);
}
-.library-tab > span { position: relative; display: grid; place-items: center; width: 22px; height: 22px; }
-.library-tab .icon { width: 20px; height: 20px; stroke-width: 1.45; }
-.library-tab > strong { overflow: hidden; font-size: 11px; font-weight: 600; line-height: 14px; text-overflow: ellipsis; white-space: nowrap; }
-.library-tab > small {
- position: absolute;
- top: 7px;
- left: calc(50% + 9px);
- min-width: 15px;
- height: 15px;
- padding: 0 4px;
- border-radius: 8px;
- background: #33363c;
- color: #cfd2d8;
- font: 600 9px/15px var(--font-ui);
-}
-.library-tab > small:empty { display: none; }
+.library-tab > span { position: relative; display: grid; place-items: center; width: 16px; height: 16px; flex: none; }
+.library-tab > strong { overflow: hidden; font-size: 12px; font-weight: 500; text-overflow: ellipsis; white-space: nowrap; }
.library-view { flex: 1; min-width: 0; min-height: 0; display: none; flex-direction: column; }
.library-view.active { display: flex; }
.library-toolbar {
@@ -320,59 +306,64 @@ button:focus-visible, textarea:focus-visible {
.library.is-refreshing .library-refresh .icon { animation: library-spin 700ms linear infinite; }
@keyframes library-spin { to { transform: rotate(360deg); } }
-.source-browser { flex: 1; min-width: 0; min-height: 0; display: grid; grid-template-columns: minmax(104px, 29%) minmax(0, 1fr); }
+.source-workspace {
+ flex: 1;
+ min-width: 0;
+ min-height: 0;
+ display: grid;
+ grid-template-columns: 44px minmax(0, 1fr);
+ grid-template-rows: 36px minmax(0, 1fr);
+}
+.source-sidebar-heading,
+.source-code-heading {
+ min-width: 0;
+ display: flex;
+ align-items: center;
+ border-bottom: 1px solid var(--line);
+ background: #151619;
+}
+.source-sidebar-heading { justify-content: center; border-right: 1px solid var(--line); }
+.source-sidebar-mark { width: 28px; height: 28px; display: grid; place-items: center; color: var(--text-3); }
+.source-sidebar-mark .icon { width: 14px; height: 14px; }
+.source-code-heading { padding: 0 7px 0 10px; }
+.source-code-heading .code-toolbar { width: 100%; }
.source-files {
min-width: 0;
min-height: 0;
- overflow: auto;
- padding: 7px 6px 24px;
+ overflow-y: auto;
+ overflow-x: hidden;
+ padding: 4px 5px 24px;
border-right: 1px solid var(--line);
background: #121316;
+ scrollbar-width: none;
}
+.source-files::-webkit-scrollbar { width: 0; }
.source-file {
- width: 100%;
- min-width: 0;
+ width: 32px;
+ height: 32px;
display: grid;
- grid-template-columns: 24px minmax(0, 1fr);
+ grid-template-columns: 16px;
+ justify-content: center;
align-items: center;
- gap: 6px;
- margin-bottom: 3px;
- padding: 7px 6px;
- border: 1px solid transparent;
- border-radius: 6px;
+ margin: 0 auto 2px;
+ padding: 0;
+ border: 0;
+ border-radius: var(--timeline-item-radius);
background: transparent;
color: #858a93;
text-align: left;
- transition: background 100ms ease, border-color 100ms ease, color 100ms ease;
+ transition: color 100ms ease;
}
-.source-file:hover { background: #1a1c20; color: #bfc2c9; }
+.source-file:hover { color: #bfc2c9; }
.source-file.active {
- border-color: color-mix(in srgb, var(--interaction-accent) 25%, #2d3036);
- background: color-mix(in srgb, var(--interaction-accent) 10%, #1b1c20);
- color: #eef0f3;
+ background: #181a1f;
+ color: #cfd2d8;
}
-.source-file-icon { width: 24px; height: 24px; display: grid; place-items: center; border-radius: 5px; background: #22242a; color: #8e939d; }
-.source-file.active .source-file-icon { background: var(--brand-soft); color: var(--interaction-accent); }
+.source-file-icon { width: 16px; height: 16px; display: grid; place-items: center; color: #858a93; }
+.source-file.active .source-file-icon { color: #858a93; }
.source-file-icon .icon { width: 14px; height: 14px; }
-.source-file-copy { min-width: 0; }
-.source-file-copy strong, .source-file-copy small { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.source-file-copy strong { color: inherit; font-size: 10px; font-weight: 600; }
-.source-file-copy small { margin-top: 1px; color: #5f636c; font: 8px/1.2 var(--font-mono); }
-.source-file em {
- grid-column: 2;
- justify-self: start;
- margin-top: -2px;
- color: #777c85;
- font: normal 600 8px/1 var(--font-ui);
- text-transform: uppercase;
-}
.source-code { min-width: 0; min-height: 0; overflow: hidden; }
.source-code > .code { height: 100%; }
-.source-code .pane-heading { height: 38px; padding-right: 7px; padding-left: 9px; background: #151619; }
-.source-code .pane-tabs { gap: 8px; }
-.source-code .pane-tab { font: 600 9px/1 var(--font-mono); letter-spacing: .04em; }
-.source-code .pane-tab.active::after { right: 2px; left: 2px; }
-.source-code .code-location { max-width: min(210px, 23vw); color: #777b84; font: 9px/1.2 var(--font-mono); }
.source-code .code-scroll { background: #141518; }
.library-context-row { flex: none; min-height: 36px; padding: 7px 10px; border-bottom: 1px solid rgba(255, 255, 255, .04); background: #141518; }
@@ -449,13 +440,14 @@ button:focus-visible, textarea:focus-visible {
.library-empty strong { color: #aeb2ba; font-size: 11px; font-weight: 600; }
.library-empty p { max-width: 260px; margin: 6px 0 0; color: #666b74; font-size: 9px; line-height: 1.55; }
-.code { flex: 1; min-width: 0; min-height: 0; display: flex; flex-direction: column; }
+.code { --code-inline-end: 12px; flex: 1; min-width: 0; min-height: 0; display: flex; flex-direction: column; }
+.code-toolbar { min-width: 0; display: flex; align-items: center; justify-content: space-between; gap: 8px; }
.code-actions { display: flex; align-items: center; gap: 5px; }
.code-location {
- max-width: 130px;
+ min-width: 0;
overflow: hidden;
- color: var(--text-3);
- font-size: 11px;
+ color: #cfd2d8;
+ font: 600 10px/1.2 var(--font-mono);
text-overflow: ellipsis;
white-space: nowrap;
}
@@ -468,7 +460,7 @@ button:focus-visible, textarea:focus-visible {
flex: 1;
min-height: 0;
overflow: auto;
- padding: 10px 10px 42px 0;
+ padding: 10px 0 42px;
background: #141518;
font: 11px/19px var(--font-mono);
user-select: text;
@@ -480,7 +472,7 @@ button:focus-visible, textarea:focus-visible {
width: 100%;
resize: none;
overflow: auto;
- padding: 10px 12px 42px 46px;
+ padding: 10px var(--code-inline-end) 42px 46px;
border: 0;
outline: none;
background: #141518;
@@ -491,6 +483,11 @@ button:focus-visible, textarea:focus-visible {
user-select: text;
white-space: pre;
}
+.code-wrap[aria-pressed="true"] { background: #24262a; color: #cfd2d8; }
+.code.is-wrapped .code-scroll { overflow-x: hidden; }
+.code.is-wrapped .code-line { width: 100%; }
+.code.is-wrapped .code-line code { min-width: 0; flex: 1; white-space: pre-wrap; overflow-wrap: anywhere; }
+.code.is-wrapped .code-editor { white-space: pre-wrap; overflow-wrap: anywhere; }
.code.is-editing .code-scroll { display: none; }
.code.is-editing .code-editor { display: block; }
.code-line { position: relative; display: flex; align-items: flex-start; width: max-content; min-width: 100%; min-height: 19px; }
@@ -502,7 +499,7 @@ button:focus-visible, textarea:focus-visible {
text-align: right;
user-select: none;
}
-.code-line code { flex: none; padding-right: 12px; color: #bebebe; font: inherit; white-space: pre; }
+.code-line code { flex: none; padding-right: var(--code-inline-end); color: #bebebe; font: inherit; white-space: pre; }
.tok-header, .tok-comment { color: #4e5358; font-style: italic; }
.tok-punct { color: #686c71; }
.tok-tag { color: #6896c6; }
@@ -583,108 +580,333 @@ button:focus-visible, textarea:focus-visible {
.stage-mute { margin-left: 5px; }
/* Inspector */
+.workspace-panel,
+.workspace-panel * {
+ scrollbar-width: none;
+ -ms-overflow-style: none;
+}
+.workspace-panel::-webkit-scrollbar,
+.workspace-panel *::-webkit-scrollbar { width: 0; height: 0; }
.workspace-scroll { flex: 1; min-width: 0; min-height: 0; overflow: auto; overscroll-behavior: contain; }
.workspace-section, .inspector { min-width: 0; }
.inspector { display: flex; flex-direction: column; }
-.selection-hero {
+.inspector-domain-tabs {
+ justify-content: flex-start;
+ gap: 18px;
+ padding: 0 10px;
+ overflow: hidden;
+}
+.inspector-domain-tab {
+ position: relative;
+ height: 100%;
min-width: 0;
- display: grid;
- grid-template-columns: 28px minmax(0, 1fr) auto;
+ display: flex;
align-items: center;
- gap: 8px;
- padding: 10px 12px;
- border-bottom: 1px solid var(--line);
+ gap: 7px;
+ padding: 0 2px;
+ border: 0;
+ background: transparent;
+ color: var(--text-2);
+}
+.inspector-domain-tab > strong { font-size: 12px; font-weight: 500; white-space: nowrap; }
+.inspector-domain-tab.active { color: var(--interaction-accent); }
+.inspector-domain-tab.active::after {
+ content: "";
+ position: absolute;
+ right: 0;
+ bottom: -1px;
+ left: 0;
+ height: 2px;
+ border-radius: 2px 2px 0 0;
+ background: var(--interaction-accent);
+ box-shadow: 0 -3px 12px color-mix(in srgb, var(--interaction-accent) 28%, transparent);
+}
+.inspector-subtabs {
+ min-height: 28px;
+ display: flex;
+ align-items: center;
+ gap: 2px;
+ margin: 10px 12px 4px;
+ padding: 2px;
+ border-radius: 5px;
+ background: #101114;
+ overflow: hidden;
}
-.selection-icon { width: 28px; height: 28px; display: grid; place-items: center; color: var(--text-2); }
-.selection-title { min-width: 0; }
-.selection-title strong, .selection-title small {
+.inspector-subtab {
+ min-width: 0;
+ width: 0;
+ flex: 1 1 0;
+ height: 24px;
+ overflow: hidden;
+ padding: 0 5px;
+ border: 0;
+ border-radius: 4px;
+ background: transparent;
+ color: var(--text-3);
+ white-space: nowrap;
+}
+.inspector-subtab > span {
display: block;
- max-width: 100%;
overflow: hidden;
- text-overflow: ellipsis;
+ font-size: 11px;
+ font-weight: 500;
+ line-height: 1;
white-space: nowrap;
}
-.selection-title strong { color: var(--text); font-size: 12px; font-weight: 500; }
-.selection-title small { margin-top: 1px; color: var(--text-3); font-size: 11px; }
-.selection-kind { color: var(--text-3); font-size: 11px; text-transform: capitalize; }
-.property-group { min-width: 0; padding: 11px 12px; border-bottom: 1px solid var(--line); }
-.property-group h3 { margin: 0 0 6px; color: #c4c6cc; font-size: 11px; font-weight: 500; }
+.inspector-subtab.active { background: #24262a; color: #c9cbd0; }
+.inspector-empty { padding: 28px 14px; color: var(--text-3); font-size: 11px; text-align: center; }
+.property-group { min-width: 0; padding: 14px 14px 16px; border-bottom: 1px solid var(--line); }
+.property-group h3 { margin: 0 0 10px; color: #c4c6cc; font-size: 11px; font-weight: 500; }
.property-grid { min-width: 0; }
.property {
min-width: 0;
min-height: 30px;
display: grid;
- grid-template-columns: minmax(76px, .8fr) minmax(0, 1.2fr);
- align-items: center;
- gap: 10px;
+ grid-template-columns: 80px minmax(0, 1fr);
+ align-items: start;
+ gap: 24px;
+ padding: 5px 0;
}
.property > span {
overflow: hidden;
color: var(--text-3);
font-size: 11px;
+ line-height: 18px;
text-overflow: ellipsis;
white-space: nowrap;
}
.property > strong {
min-width: 0;
- overflow: hidden;
+ overflow: visible;
color: var(--text-2);
font-size: 11px;
font-weight: 500;
- text-align: right;
- text-overflow: ellipsis;
- white-space: nowrap;
+ line-height: 18px;
+ overflow-wrap: anywhere;
+ text-align: left;
+ white-space: normal;
font-variant-numeric: tabular-nums;
}
-.property-code > strong { font: 11px/1.3 var(--font-mono); }
+.property-code > strong { font: 11px/18px var(--font-mono); }
.property-number > strong { font-family: var(--font-mono); font-variant-numeric: tabular-nums; }
-.parameter-group .property-grid { display: flex; flex-direction: column; gap: 4px; }
+.parameter-group .property-grid { display: flex; flex-direction: column; gap: 7px; }
.parameter-row {
min-width: 0;
- min-height: 32px;
+ min-height: 30px;
display: grid;
- grid-template-columns: minmax(76px, .8fr) minmax(0, 1.2fr);
- grid-template-rows: 20px 12px;
- column-gap: 10px;
+ grid-template-columns: minmax(76px, 1fr) minmax(96px, 132px);
+ column-gap: 16px;
align-items: center;
- padding: 2px 0;
+ padding: 1px 0;
}
-.parameter-row.parameter-declared { grid-template-rows: 24px; }
.parameter-label { min-width: 0; overflow: hidden; color: var(--text-3); font-size: 11px; text-overflow: ellipsis; white-space: nowrap; }
-.parameter-right { min-width: 0; display: flex; align-items: center; justify-content: flex-end; gap: 4px; }
+.parameter-right { min-width: 0; display: flex; align-items: center; justify-content: flex-start; gap: 5px; }
.parameter-value {
min-width: 0;
width: 100%;
box-sizing: border-box;
- border: 1px solid var(--line-strong);
- border-radius: 3px;
- padding: 3px 6px;
- background: var(--panel-2);
+ border: 1px solid #2b2e34;
+ border-radius: 4px;
+ padding: 5px 7px;
+ background: #1a1b1f;
color: var(--text);
font: 11px/1.2 var(--font-mono);
font-variant-numeric: tabular-nums;
text-align: right;
+ caret-color: var(--interaction-accent);
+ cursor: text !important;
}
-.parameter-value:focus { outline: 1px solid var(--brand-500); outline-offset: 1px; }
-.parameter-readonly .parameter-value { border: 0; padding-right: 0; background: transparent; color: var(--text-2); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.parameter-source { grid-column: 1 / -1; min-width: 0; overflow: hidden; color: var(--text-3); font: 9px/1 var(--font-mono); opacity: .7; text-overflow: ellipsis; white-space: nowrap; }
-.parameter-right > small { flex: none; color: var(--text-3); font-size: 10px; }
-.operation-group .property-grid { display: flex; flex-direction: column; gap: 2px; }
-.operation-row {
- min-height: 26px;
+.parameter-value:focus { border-color: #6a6e77; outline: 0; background: #131417; }
+.control-boolean .parameter-right { justify-content: flex-end; }
+.control-boolean .parameter-value {
+ appearance: none;
+ width: 34px;
+ height: 18px;
+ flex: none;
+ position: relative;
+ border: 0;
+ border-radius: 10px;
+ padding: 0;
+ background: #292b30;
+ cursor: default !important;
+}
+.control-boolean .parameter-value::before {
+ content: "";
+ position: absolute;
+ top: 3px;
+ left: 3px;
+ width: 12px;
+ height: 12px;
+ border-radius: 50%;
+ background: #a9acb3;
+ transition: transform 100ms ease;
+}
+.control-boolean .parameter-value:focus-visible { box-shadow: 0 0 0 1px #777b84; }
+.control-boolean .parameter-value:checked { background: #45484f; }
+.control-boolean .parameter-value:checked::before { transform: translateX(16px); background: #f2f3f5; }
+.parameter-color {
+ position: relative;
+ width: 25px;
+ height: 25px;
+ display: grid;
+ place-items: stretch;
+ flex: none;
+ padding: 3px;
+ border: 1px solid #2b2e34;
+ border-radius: 4px;
+ background: #1a1b1f;
+ overflow: hidden;
+}
+.parameter-color:focus-within,
+.parameter-color[data-open="true"] { border-color: #6a6e77; outline: 0; background: #131417; }
+.parameter-color-swatch { display: block; min-width: 0; min-height: 0; border-radius: 2px; box-shadow: inset 0 0 0 1px rgba(255, 255, 255, .08); }
+.parameter-color-field { min-width: 0; width: 100%; display: grid; grid-template-columns: 25px minmax(0, 1fr); align-items: center; gap: 5px; }
+.parameter-color-native {
+ position: absolute;
+ inset: 0;
+ width: 100%;
+ height: 100%;
+ opacity: 0;
+ cursor: pointer;
+}
+.parameter-color-value { width: min(100%, 102px); }
+.control-list,
+.control-record { grid-template-columns: minmax(0, 1fr); align-items: stretch; gap: 6px; }
+.control-list .parameter-right,
+.control-record .parameter-right { grid-column: 1 / -1; width: 100%; }
+.parameter-structured { min-width: 0; width: 100%; }
+.parameter-structured-summary {
+ min-height: 20px;
+ display: flex;
+ align-items: center;
+ justify-content: flex-end;
+ color: #6f737c;
+ font: 10px/1 var(--font-mono);
+}
+.parameter-list-items { display: flex; flex-direction: column; gap: 5px; }
+.parameter-list-item {
+ min-width: 0;
display: grid;
grid-template-columns: minmax(0, 1fr) auto;
align-items: center;
- gap: 10px;
- padding: 0 2px;
- border-bottom: 1px solid rgba(255,255,255,.035);
-}
-.operation-row:last-child { border-bottom: 0; }
-.operation-copy { min-width: 0; display: flex; flex-direction: column; gap: 2px; }
-.operation-label { color: var(--text-2); font-size: 11px; }
-.operation-detail { min-width: 0; overflow: hidden; color: var(--text-3); font: 9px/1.2 var(--font-mono); text-overflow: ellipsis; white-space: nowrap; }
-.operation-state { color: var(--text-3); font-size: 10px; font-weight: 500; }
-.operation-enabled .operation-state { color: var(--text); }
+ gap: 5px;
+ padding: 5px;
+ border: 1px solid #272a30;
+ border-radius: 5px;
+ background: #17181c;
+}
+.parameter-list-item.record { align-items: start; }
+.parameter-list-actions { display: flex; align-items: center; gap: 2px; }
+.parameter-list-actions button {
+ width: 20px;
+ height: 22px;
+ display: grid;
+ place-items: center;
+ padding: 0;
+ border: 0;
+ border-radius: 3px;
+ background: transparent;
+ color: #747881;
+ font: 10px/1 var(--font-ui);
+}
+.parameter-list-actions button:disabled { color: #34373d; }
+.parameter-list-actions button:not(:disabled):focus-visible { outline: 1px solid #62666f; }
+.parameter-list-actions .icon { width: 11px; height: 11px; }
+.parameter-record-fields { min-width: 0; display: flex; flex-direction: column; gap: 5px; }
+.parameter-record-field {
+ min-width: 0;
+ display: grid;
+ grid-template-columns: 58px minmax(0, 1fr);
+ align-items: center;
+ gap: 7px;
+}
+.parameter-record-field > span:first-child {
+ overflow: hidden;
+ color: #6f737c;
+ font-size: 10px;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+.parameter-structured-footer {
+ min-height: 30px;
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 8px;
+ padding-top: 6px;
+}
+.parameter-structured-footer button {
+ min-height: 24px;
+ padding: 0 7px;
+ border: 1px solid #2b2e34;
+ border-radius: 4px;
+ background: #191a1e;
+ color: #8c9098;
+ font: 10px/1 var(--font-ui);
+}
+.parameter-structured-footer button:disabled { color: #454850; background: #16171a; }
+.parameter-structured-footer button.primary:not(:disabled) { border-color: #555962; background: #292b30; color: #e0e2e6; }
+.parameter-structured-add { display: inline-flex; align-items: center; gap: 4px; }
+.parameter-structured-add .icon { width: 11px; height: 11px; }
+.parameter-structured-decisions { display: flex; align-items: center; gap: 4px; margin-left: auto; }
+.parameter-select { position: relative; width: 100%; min-width: 0; }
+.parameter-select-trigger {
+ width: 100%;
+ min-width: 0;
+ height: 27px;
+ display: grid;
+ grid-template-columns: minmax(0, 1fr) 12px;
+ align-items: center;
+ gap: 5px;
+ padding: 0 6px 0 8px;
+ border: 1px solid #2b2e34;
+ border-radius: 4px;
+ background: #1a1b1f;
+ color: var(--text);
+ font: 11px/1.2 var(--font-mono);
+}
+.parameter-select-trigger:focus-visible,
+.parameter-select.open .parameter-select-trigger {
+ border-color: #6a6e77;
+ outline: 0;
+ background: #131417;
+}
+.parameter-select-value { min-width: 0; overflow: hidden; text-align: right; white-space: nowrap; }
+.parameter-select-chevron { display: grid; place-items: center; color: #747881; transition: transform 100ms ease; }
+.parameter-select-chevron .icon { width: 12px; height: 12px; }
+.parameter-select.open .parameter-select-chevron { transform: rotate(180deg); }
+.parameter-select-menu {
+ position: absolute;
+ z-index: 30;
+ top: calc(100% + 4px);
+ right: 0;
+ width: 100%;
+ max-height: 184px;
+ overflow-y: auto;
+ padding: 3px;
+ border: 1px solid #34373e;
+ border-radius: 5px;
+ background: #15161a;
+ 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-menu[hidden] { display: none; }
+.parameter-select-option {
+ width: 100%;
+ min-height: 27px;
+ overflow: hidden;
+ padding: 0 8px;
+ border: 0;
+ border-radius: 3px;
+ background: transparent;
+ color: #8e929a;
+ font: 11px/1.2 var(--font-mono);
+ text-align: right;
+ white-space: nowrap;
+}
+.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; }
.status.saving { color: var(--text-2); }
.status.saved { color: var(--ok); }
diff --git a/packages/studio/src/ui/code.ts b/packages/studio/src/ui/code.ts
index a0c796c9..3bce4a63 100644
--- a/packages/studio/src/ui/code.ts
+++ b/packages/studio/src/ui/code.ts
@@ -18,6 +18,7 @@ export type Highlight = {
};
export type CodePane = {
+ readonly toolbar: HTMLElement;
readonly element: HTMLElement;
/** Returns false only while an unsaved file is being saved before a switch. */
show(snapshot: StudioSnapshot, source?: StudioSourceView): boolean;
@@ -70,31 +71,32 @@ function roundedRangePath(points: readonly { x: number; y: number }[], radius =
const RANGE_LEFT = 41;
export function createCodePane(): CodePane {
+ const toolbar = document.createElement("div");
+ toolbar.className = "code-toolbar";
+ toolbar.innerHTML = `
+ <strong class="code-location" data-path></strong>
+ <div class="code-actions">
+ <span class="code-save-state" data-save-state></span>
+ <button type="button" class="icon-button code-wrap" data-wrap aria-label="Wrap lines" aria-pressed="false" title="Wrap lines">
+ ${icon("wrap")}
+ </button>
+ <button type="button" class="icon-button code-mode" data-mode aria-label="Edit source" title="Edit source">
+ <span data-mode-icon>${icon("edit")}</span>
+ </button>
+ </div>`;
const element = document.createElement("section");
element.className = "code";
element.innerHTML = `
- <div class="pane-heading code-heading">
- <div class="pane-tabs" role="tablist" aria-label="Workspace views">
- <button type="button" class="pane-tab active source-language" role="tab" aria-selected="true" data-language>SVML</button>
- </div>
- <div class="code-actions">
- <span class="code-location" data-path></span>
- <span class="code-save-state" data-save-state></span>
- <button type="button" class="icon-button code-mode" data-mode aria-label="Edit source" title="Edit source">
- <span data-mode-icon>${icon("edit")}</span>
- </button>
- </div>
- </div>
<div class="code-scroll"><svg class="range-canvas" aria-hidden="true"></svg></div>
<textarea class="code-editor" data-editor spellcheck="false" aria-label="SVML source"></textarea>`;
- const path = element.querySelector<HTMLElement>("[data-path]")!;
- const language = element.querySelector<HTMLElement>("[data-language]")!;
+ const path = toolbar.querySelector<HTMLElement>("[data-path]")!;
const scroll = element.querySelector<HTMLElement>(".code-scroll")!;
const canvas = element.querySelector<SVGSVGElement>(".range-canvas")!;
const editor = element.querySelector<HTMLTextAreaElement>("[data-editor]")!;
- const mode = element.querySelector<HTMLButtonElement>("[data-mode]")!;
+ const wrap = toolbar.querySelector<HTMLButtonElement>("[data-wrap]")!;
+ const mode = toolbar.querySelector<HTMLButtonElement>("[data-mode]")!;
const modeIcon = mode.querySelector<HTMLElement>("[data-mode-icon]")!;
- const saveState = element.querySelector<HTMLElement>("[data-save-state]")!;
+ const saveState = toolbar.querySelector<HTMLElement>("[data-save-state]")!;
let lines: Line[] = [];
let current: readonly Highlight[] = [];
@@ -108,6 +110,16 @@ export function createCodePane(): CodePane {
let dirty = false;
let saveInFlight = false;
let saveTimer: number | undefined;
+ let wrapped = false;
+
+ const setWrapped = (value: boolean): void => {
+ wrapped = value;
+ element.classList.toggle("is-wrapped", wrapped);
+ wrap.setAttribute("aria-pressed", String(wrapped));
+ wrap.setAttribute("aria-label", wrapped ? "Keep lines unwrapped" : "Wrap lines");
+ wrap.title = wrapped ? "Keep lines unwrapped" : "Wrap lines";
+ window.requestAnimationFrame(draw);
+ };
const setEditing = (value: boolean): void => {
editing = value;
@@ -170,6 +182,7 @@ export function createCodePane(): CodePane {
if (editing && dirty) void save();
setEditing(!editing);
});
+ wrap.addEventListener("click", () => setWrapped(!wrapped));
editor.addEventListener("input", () => {
dirty = true;
saveState.textContent = "Unsaved";
@@ -229,7 +242,10 @@ export function createCodePane(): CodePane {
};
const draw = (): void => {
- const width = Math.max(scroll.clientWidth, scroll.scrollWidth);
+ // In wrapped mode the viewport is the content width. Reusing scrollWidth
+ // here would let the previous wide SVG keep itself wide forever after a
+ // mode switch, because that absolute canvas also contributes to scrollWidth.
+ const width = wrapped ? scroll.clientWidth : Math.max(scroll.clientWidth, scroll.scrollWidth);
const last = lines.at(-1)?.element;
const height = Math.max(scroll.clientHeight, last === undefined ? 0 : last.offsetTop + last.offsetHeight);
canvas.setAttribute("width", String(width));
@@ -245,7 +261,8 @@ export function createCodePane(): CodePane {
const lineHeight = start.height || Number.parseFloat(getComputedStyle(scroll).lineHeight) || 20;
// The outline starts at the code column rather than over the line number.
const left = RANGE_LEFT;
- const right = width - 10;
+ const rightInset = Number.parseFloat(getComputedStyle(element).getPropertyValue("--code-inline-end")) || 12;
+ const right = width - rightInset;
const startX = Math.max(left, start.x - 3);
const endX = Math.max(left, end.x + 3);
const top = start.y - lineHeight / 2;
@@ -274,6 +291,7 @@ export function createCodePane(): CodePane {
new ResizeObserver(draw).observe(scroll);
return {
+ toolbar,
element,
show(snapshot, selected) {
const sourceFile = selected
@@ -294,9 +312,8 @@ export function createCodePane(): CodePane {
if (activeSource !== undefined && activeSource.path !== sourceFile.path && editing) setEditing(false);
activeSource = sourceFile;
authorPath = snapshot.source.path;
- path.textContent = sourceFile.path;
+ path.textContent = sourceFile.path.split(/[\\/]/u).filter(Boolean).at(-1) ?? sourceFile.path;
path.title = sourceFile.path;
- language.textContent = sourceFile.language.toUpperCase();
const source = sourceFile.text;
snapshotRevision = snapshot.revision;
sourceText = source;
diff --git a/packages/studio/src/ui/icons.ts b/packages/studio/src/ui/icons.ts
index 98b37998..d3ec57db 100644
--- a/packages/studio/src/ui/icons.ts
+++ b/packages/studio/src/ui/icons.ts
@@ -1,10 +1,21 @@
const paths: Readonly<Record<string, string>> = {
+ brand: '<g transform="translate(0 1.282) scale(.091603) translate(-50 -180)"><path fill="currentColor" stroke="none" d="M303.78,277.82c-5.98-8.63-15.83-13.77-26.32-13.77h-93.41c-12.28,0-24.92,7.44-29.6,18.8l-28.26,75.82c-4.6,11.25-4.54,24.05,2.22,34.16,6.79,10.15,19.36,16.15,31.57,16.15h85.98c14.12,0,26.9-8.88,31.84-22.1l29.69-79.57c3.67-9.84,2.29-20.86-3.69-29.48v-.02h-.02ZM252.02,377.25c-.94,2.52-3.39,4.22-6.08,4.22h-83.45c-4.34,0-6.68-2.8-7.49-3.99s-2.5-4.43-.84-8.44l23.85-66.24c2.29-6.35,8.08-10.87,14.82-11.22.33-.02.67-.02,1.02-.02h75.41s12.51,1.42,9.29,14.61l-26.53,71.09h0ZM106.85,361.73s-22.36-11.59-17.66-32.66l29.67-82.23c4.78-13.25,17.36-22.09,31.45-22.09h95.02c6.25,0,12.1,3.03,15.71,8.14l13.89,19.68h-112.97c-8.7,0-16.49,5.41-19.52,13.57l-35.59,95.6h0ZM73.3,323.27s-22.37-11.59-17.66-32.66l29.67-82.23c4.79-13.25,17.37-22.09,31.45-22.09h89.91c6.25,0,12.1,3.03,15.71,8.14l13.89,19.68h-107.84c-8.7,0-16.49,5.41-19.52,13.57l-35.59,95.6h-.02Z"/></g>',
code: '<path d="M9 7 4 12l5 5M15 7l5 5-5 5M13 4l-2 16"/>',
edit: '<path d="m4 16-.8 4 4-.8L18.5 8.9 15.1 5.5 4 16Z"/><path d="m13.8 6.8 3.4 3.4"/>',
eye: '<path d="M2.5 12s3.5-6 9.5-6 9.5 6 9.5 6-3.5 6-9.5 6-9.5-6-9.5-6Z"/><circle cx="12" cy="12" r="2.5"/>',
preview: '<rect x="3" y="4" width="18" height="14" rx="2"/><path d="m10 8 5 3.5-5 3.5V8ZM8 21h8"/>',
tune: '<path d="M4 7h10M18 7h2M4 17h2M10 17h10"/><circle cx="16" cy="7" r="2"/><circle cx="8" cy="17" r="2"/>',
+ where: '<rect x="6" y="6" width="12" height="12" rx="1"/><path d="M12 2v7M12 15v7M2 12h7M15 12h7"/>',
+ how: '<path d="M6 3v18M12 3v18M18 3v18"/><rect x="4" y="7" width="4" height="5" rx="1"/><rect x="10" y="13" width="4" height="5" rx="1"/><rect x="16" y="5" width="4" height="5" rx="1"/>',
+ when: '<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3.5 2M4.5 4.5 2.5 7M19.5 4.5 21.5 7"/>',
+ chevron: '<path d="m7 9 5 5 5-5"/>',
select: '<path d="M5 3v15l4-4 3 6 3-1.5-3-6h6L5 3Z"/>',
+ tasks: '<path d="M10 6h10M10 12h10M10 18h10"/><path d="m3.5 6 1.5 1.5L7.5 4.5M3.5 12 5 13.5l2.5-3M3.5 18 5 19.5l2.5-3"/>',
+ archive: '<path d="M4 8v12h16V8M3 4h18v4H3zM9 12h6"/>',
+ run: '<circle cx="12" cy="12" r="9"/><path d="m10 8 6 4-6 4V8Z"/>',
+ image: '<rect x="3" y="4" width="18" height="16" rx="2"/><circle cx="8.5" cy="9" r="2"/><path d="m4 18 5-5 3 3 3-4 5 6"/>',
+ sidebarCollapse: '<rect x="3" y="4" width="18" height="16" rx="2"/><path d="M8 4v16m7-11-3 3 3 3"/>',
+ wrap: '<path d="M4 6h16M4 10h12a4 4 0 0 1 0 8h-5m3-3-3 3 3 3M4 14h5M4 18h4"/>',
timeline: '<path d="M3 6h18M3 12h18M3 18h18"/><path d="M8 4v4M16 10v4M11 16v4"/>',
minus: '<path d="M5 12h14"/>',
plus: '<path d="M12 5v14M5 12h14"/>',
diff --git a/packages/studio/src/ui/library.ts b/packages/studio/src/ui/library.ts
index ba69d20c..0ad8195e 100644
--- a/packages/studio/src/ui/library.ts
+++ b/packages/studio/src/ui/library.ts
@@ -20,6 +20,12 @@ function leaf(path: string): string {
return path.split(/[\\/]/u).filter(Boolean).at(-1) ?? path;
}
+function stem(path: string): string {
+ const name = leaf(path);
+ const dot = name.lastIndexOf(".");
+ return dot > 0 ? name.slice(0, dot) : name;
+}
+
function compactId(value: string): string {
return value.length <= 18 ? value : `${value.slice(0, 9)}…${value.slice(-6)}`;
}
@@ -89,7 +95,7 @@ function taskCard(task: StudioTaskView): HTMLElement {
function artifactKind(mediaType: string): { readonly label: string; readonly icon: string } {
if (mediaType.startsWith("video/")) return { label: "Video", icon: "video" };
- if (mediaType.startsWith("image/")) return { label: "Image", icon: "preview" };
+ if (mediaType.startsWith("image/")) return { label: "Image", icon: "image" };
if (mediaType.startsWith("audio/")) return { label: "Audio", icon: "waveform" };
return { label: "Data", icon: "code" };
}
@@ -134,18 +140,18 @@ export function createLibraryPane(code: CodePane): LibraryPane {
<span>${icon("code")}</span><strong>Source</strong>
</button>
<button type="button" class="library-tab" data-library-tab="tasks" role="tab" aria-selected="false">
- <span>${icon("timeline")}</span><strong>Tasks</strong><small data-task-badge></small>
+ <span>${icon("tasks")}</span><strong>Tasks</strong>
</button>
<button type="button" class="library-tab" data-library-tab="artifacts" role="tab" aria-selected="false">
- <span>${icon("layers")}</span><strong>Artifacts</strong><small data-artifact-badge></small>
+ <span>${icon("archive")}</span><strong>Artifacts</strong>
</button>
</div>
<section class="library-view active" data-library-view="source">
- <div class="library-toolbar">
- <div><strong>Live closure</strong><small data-source-count></small></div>
- <span class="library-context">Run → Author</span>
- </div>
- <div class="source-browser">
+ <div class="source-workspace" data-source-workspace>
+ <div class="source-sidebar-heading">
+ <span class="source-sidebar-mark" aria-hidden="true">${icon("sidebarCollapse")}</span>
+ </div>
+ <div class="source-code-heading" data-source-toolbar></div>
<nav class="source-files" aria-label="Referenced source files" data-source-files></nav>
<div class="source-code" data-source-code></div>
</div>
@@ -167,14 +173,13 @@ export function createLibraryPane(code: CodePane): LibraryPane {
<div class="artifact-grid" data-artifact-grid></div>
</section>`;
+ element.querySelector<HTMLElement>("[data-source-toolbar]")!.append(code.toolbar);
element.querySelector<HTMLElement>("[data-source-code]")!.append(code.element);
const sourceList = element.querySelector<HTMLElement>("[data-source-files]")!;
const taskList = element.querySelector<HTMLElement>("[data-task-list]")!;
const artifactGrid = element.querySelector<HTMLElement>("[data-artifact-grid]")!;
const artifactFilters = element.querySelector<HTMLElement>("[data-artifact-filters]")!;
const runtimeContext = element.querySelector<HTMLElement>("[data-runtime-context]")!;
- const taskBadge = element.querySelector<HTMLElement>("[data-task-badge]")!;
- const artifactBadge = element.querySelector<HTMLElement>("[data-artifact-badge]")!;
let snapshot: StudioSnapshot | undefined;
let selectedSource = "";
let active: LibrarySection = "source";
@@ -196,10 +201,8 @@ export function createLibraryPane(code: CodePane): LibraryPane {
const button = document.createElement("button");
button.type = "button";
button.className = `source-file${file.path === selectedSource ? " active" : ""}`;
- button.innerHTML = `<span class="source-file-icon">${icon(file.language === "svrun" ? "timeline" : file.language === "svs" ? "tune" : "code")}</span><span class="source-file-copy"><strong></strong><small></small></span><em></em>`;
- button.querySelector("strong")!.textContent = leaf(file.path);
- button.querySelector("small")!.textContent = file.path;
- button.querySelector("em")!.textContent = file.role === "dependency" ? file.language : file.role;
+ button.innerHTML = `<span class="source-file-icon">${icon(file.language === "svrun" ? "run" : file.language === "svs" ? "tune" : "code")}</span>`;
+ button.setAttribute("aria-label", `${stem(file.path)} ${file.language.toUpperCase()}`);
button.title = `${file.role} · ${file.path}${file.imports.length === 0 ? "" : `\nimports ${file.imports.join(", ")}`}`;
button.addEventListener("click", () => {
selectedSource = file.path;
@@ -207,14 +210,11 @@ export function createLibraryPane(code: CodePane): LibraryPane {
});
return button;
}));
- element.querySelector<HTMLElement>("[data-source-count]")!.textContent = `${files.length} referenced file${files.length === 1 ? "" : "s"}`;
};
const renderTasks = (): void => {
const tasks = library?.tasks ?? [];
const runtime = library?.runtime;
- taskBadge.textContent = tasks.length === 0 ? "" : String(tasks.filter((task) =>
- ["queued", "running", "waiting", "active"].includes(task.status)).length || tasks.length);
element.querySelector<HTMLElement>("[data-task-count]")!.textContent = `${tasks.length} build${tasks.length === 1 ? "" : "s"}`;
runtimeContext.replaceChildren();
const context = document.createElement("span");
@@ -225,7 +225,7 @@ export function createLibraryPane(code: CodePane): LibraryPane {
context.title = runtime === undefined ? "No Runtime selected for this environment" : `${library!.environment}\n${runtime}`;
runtimeContext.append(context);
if (tasks.length === 0) {
- taskList.replaceChildren(emptyState("timeline",
+ taskList.replaceChildren(emptyState("tasks",
runtime === undefined ? "No Runtime selected" : "No builds yet",
runtime === undefined
? "Select one with hypit runtime use, then reopen Studio."
@@ -237,7 +237,6 @@ export function createLibraryPane(code: CodePane): LibraryPane {
const renderArtifacts = (): void => {
const artifacts = library?.artifacts ?? [];
- artifactBadge.textContent = artifacts.length === 0 ? "" : String(artifacts.length);
element.querySelector<HTMLElement>("[data-artifact-count]")!.textContent = `${artifacts.length} stored object${artifacts.length === 1 ? "" : "s"}`;
const filters = [
["all", "All"],
@@ -257,7 +256,7 @@ export function createLibraryPane(code: CodePane): LibraryPane {
? artifacts
: artifacts.filter((artifact) => artifact.mediaType.startsWith(`${artifactFilter}/`));
if (shown.length === 0) {
- artifactGrid.replaceChildren(emptyState("layers",
+ artifactGrid.replaceChildren(emptyState("archive",
artifacts.length === 0 ? "No accepted artifacts" : `No ${artifactFilter} artifacts`,
library?.runtime === undefined
? "Artifacts appear only from a selected Runtime archive."
@@ -297,8 +296,8 @@ export function createLibraryPane(code: CodePane): LibraryPane {
renderArtifacts();
} catch (error) {
const detail = error instanceof Error ? error.message : String(error);
- if (active === "tasks") taskList.replaceChildren(emptyState("timeline", "Archive unavailable", detail));
- if (active === "artifacts") artifactGrid.replaceChildren(emptyState("layers", "ArtifactStore unavailable", detail));
+ if (active === "tasks") taskList.replaceChildren(emptyState("tasks", "Archive unavailable", detail));
+ if (active === "artifacts") artifactGrid.replaceChildren(emptyState("archive", "ArtifactStore unavailable", detail));
} finally {
refreshing = false;
element.classList.remove("is-refreshing");
diff --git a/packages/studio/src/ui/main.ts b/packages/studio/src/ui/main.ts
index 4725dc03..59361efe 100644
--- a/packages/studio/src/ui/main.ts
+++ b/packages/studio/src/ui/main.ts
@@ -1,6 +1,8 @@
-import type { Clip, StudioFailure, StudioSnapshot } from "../shared.js";
+import type { Clip, StudioFailure, StudioInspectorDomain, StudioSnapshot } from "../shared.js";
+import type { CanonicalValue, ValueSchema } from "@hypit/protocol";
+import { validateParameterValue } from "../parameter-values.js";
import { createCodePane } from "./code.js";
-import { setIcon } from "./icons.js";
+import { icon } from "./icons.js";
import { createLibraryPane } from "./library.js";
import { createHandle } from "./resize.js";
import type { Highlight } from "./code.js";
@@ -42,10 +44,8 @@ app.innerHTML = `
<aside class="source-panel" data-library></aside>
<div class="preview-panel" data-stage></div>
<aside class="workspace-panel">
- <div class="pane-heading workspace-heading">
- <div class="pane-tabs" role="tablist" aria-label="Inspector views">
- <button type="button" class="pane-tab active" role="tab" aria-selected="true">Properties</button>
- </div>
+ <div class="pane-heading workspace-heading" data-workspace-heading>
+ <div class="pane-title">${icon("tune")}<h2>Properties</h2></div>
</div>
<div class="workspace-scroll">
<section class="workspace-section">
@@ -95,6 +95,7 @@ shell.insertBefore(createHandle({
remember: "hypit-studio.v3.timeline-height",
}), app.querySelector<HTMLElement>("[data-timeline]")!);
const inspector = app.querySelector<HTMLElement>("[data-inspector]")!;
+const workspaceHeading = app.querySelector<HTMLElement>("[data-workspace-heading]")!;
const meta = app.querySelector<HTMLElement>("[data-meta]")!;
const project = app.querySelector<HTMLElement>("[data-project]")!;
const status = app.querySelector<HTMLElement>("[data-status]")!;
@@ -138,128 +139,537 @@ function group(label: string, items: readonly HTMLElement[], className = ""): HT
return node;
}
-function parameterControl(entityId: string, parameter: Clip["parameters"][number]): HTMLElement {
- const row = document.createElement("label");
- row.className = `parameter-row${parameter.writable ? " parameter-editable" : " parameter-readonly"}${parameter.group === undefined ? "" : " parameter-declared"}`;
+function aspectRatio(width: number, height: number): string {
+ let a = width;
+ let b = height;
+ while (b !== 0) [a, b] = [b, a % b];
+ return `${width / a}:${height / a}`;
+}
+
+const domainPresentation: Readonly<Record<StudioInspectorDomain, { readonly label: string; readonly icon: string }>> = {
+ where: { label: "Where", icon: "where" },
+ how: { label: "How", icon: "how" },
+ when: { label: "When", icon: "when" },
+};
+const domainOrder: readonly StudioInspectorDomain[] = ["where", "how", "when"];
+const inspectorDomainByEntity = new Map<string, StudioInspectorDomain>();
+const inspectorPageByEntity = new Map<string, string>();
+
+function defaultWorkspaceHeading(): void {
+ workspaceHeading.className = "pane-heading workspace-heading";
+ workspaceHeading.innerHTML = `<div class="pane-title">${icon("tune")}<h2>Properties</h2></div>`;
+}
+
+function inspectorHeading(
+ entityId: string,
+ domains: readonly StudioInspectorDomain[],
+ active: StudioInspectorDomain,
+ select: (domain: StudioInspectorDomain) => void,
+): void {
+ workspaceHeading.className = "pane-heading workspace-heading inspector-domain-tabs";
+ workspaceHeading.replaceChildren(...domains.map((domain) => {
+ const presentation = domainPresentation[domain];
+ const button = document.createElement("button");
+ button.type = "button";
+ button.className = `inspector-domain-tab${domain === active ? " active" : ""}`;
+ button.dataset.domain = domain;
+ button.innerHTML = `${icon(presentation.icon)}<strong>${presentation.label}</strong>`;
+ button.setAttribute("aria-pressed", String(domain === active));
+ button.addEventListener("click", () => {
+ inspectorDomainByEntity.set(entityId, domain);
+ select(domain);
+ });
+ return button;
+ }));
+}
+
+function sameValue(left: CanonicalValue, right: CanonicalValue): boolean {
+ return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function textValue(value: CanonicalValue): string {
+ return typeof value === "string" ? value : value === null ? "" : String(value);
+}
+
+function commitControl(entityId: string, parameter: Clip["inspector"][number], replacement: CanonicalValue): void {
+ if (sameValue(replacement, parameter.value)) return;
+ void writeParameter(entityId, parameter, replacement);
+}
+
+let openColorPicker: {
+ readonly root: HTMLElement;
+ readonly close: () => void;
+} | undefined;
+
+document.addEventListener("click", (event) => {
+ if (openColorPicker === undefined || !(event.target instanceof Node)) return;
+ if (!openColorPicker.root.contains(event.target)) openColorPicker.close();
+}, true);
+
+document.addEventListener("keydown", (event) => {
+ if (event.key !== "Escape" || openColorPicker === undefined) return;
+ event.preventDefault();
+ event.stopPropagation();
+ openColorPicker.close();
+}, true);
+
+function selectControl(
+ entityId: string,
+ parameter: Clip["inspector"][number],
+): HTMLElement {
+ const control = document.createElement("div");
+ control.className = "parameter-select parameter-control";
+ const trigger = document.createElement("button");
+ trigger.type = "button";
+ trigger.className = "parameter-select-trigger";
+ trigger.setAttribute("aria-label", parameter.label);
+ trigger.setAttribute("aria-haspopup", "listbox");
+ trigger.setAttribute("aria-expanded", "false");
+ const selected = document.createElement("span");
+ selected.className = "parameter-select-value";
+ const current = textValue(parameter.value);
+ selected.textContent = current;
+ const chevron = document.createElement("span");
+ chevron.className = "parameter-select-chevron";
+ chevron.innerHTML = icon("chevron");
+ trigger.append(selected, chevron);
+
+ const menu = document.createElement("div");
+ menu.className = "parameter-select-menu";
+ menu.id = `${parameter.id}:options`;
+ menu.setAttribute("role", "listbox");
+ menu.setAttribute("aria-label", parameter.label);
+ menu.hidden = true;
+ trigger.setAttribute("aria-controls", menu.id);
+
+ const options = (parameter.options ?? []).map((option) => {
+ const item = document.createElement("button");
+ item.type = "button";
+ item.className = `parameter-select-option${option === current ? " active" : ""}`;
+ item.textContent = option;
+ item.setAttribute("role", "option");
+ item.setAttribute("aria-selected", String(option === current));
+ item.addEventListener("click", () => {
+ selected.textContent = option;
+ 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);
+ });
+ return item;
+ });
+ menu.append(...options);
+
+ const close = (restoreFocus: boolean): void => {
+ control.classList.remove("open", "open-up");
+ trigger.setAttribute("aria-expanded", "false");
+ menu.hidden = true;
+ if (restoreFocus) trigger.focus();
+ };
+ const open = (focus: "selected" | "first" | "last" = "selected"): void => {
+ control.classList.add("open");
+ trigger.setAttribute("aria-expanded", "true");
+ menu.hidden = false;
+ control.classList.remove("open-up");
+ const scroll = control.closest<HTMLElement>(".workspace-scroll");
+ if (scroll !== null) {
+ const menuBox = menu.getBoundingClientRect();
+ const scrollBox = scroll.getBoundingClientRect();
+ if (menuBox.bottom > scrollBox.bottom && trigger.getBoundingClientRect().top - menuBox.height >= scrollBox.top) {
+ control.classList.add("open-up");
+ }
+ }
+ const target = focus === "first" ? options[0]
+ : focus === "last" ? options.at(-1)
+ : options.find((option) => option.classList.contains("active")) ?? options[0];
+ target?.focus();
+ };
+ const moveOptionFocus = (offset: number): void => {
+ const current = options.indexOf(document.activeElement as HTMLButtonElement);
+ const next = current < 0 ? 0 : (current + offset + options.length) % options.length;
+ options[next]?.focus();
+ };
+
+ trigger.addEventListener("click", () => {
+ if (control.classList.contains("open")) close(false);
+ else open();
+ });
+ trigger.addEventListener("keydown", (event) => {
+ if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+ event.preventDefault();
+ event.stopPropagation();
+ open(event.key === "ArrowDown" ? "first" : "last");
+ } else if (event.key === "Escape" && control.classList.contains("open")) {
+ event.preventDefault();
+ event.stopPropagation();
+ close(false);
+ }
+ });
+ menu.addEventListener("keydown", (event) => {
+ if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+ event.preventDefault();
+ event.stopPropagation();
+ moveOptionFocus(event.key === "ArrowDown" ? 1 : -1);
+ } else if (event.key === "Home" || event.key === "End") {
+ event.preventDefault();
+ event.stopPropagation();
+ options[event.key === "Home" ? 0 : options.length - 1]?.focus();
+ } else if (event.key === "Escape") {
+ event.preventDefault();
+ event.stopPropagation();
+ close(true);
+ }
+ });
+ control.addEventListener("focusout", (event) => {
+ if (event.relatedTarget instanceof Node && control.contains(event.relatedTarget)) return;
+ close(false);
+ });
+ control.append(trigger, menu);
+ return control;
+}
+
+function colorValueControl(
+ label: string,
+ initial: string,
+ change: (value: string) => void,
+ draft = false,
+): HTMLElement {
+ const field = document.createElement("span");
+ field.className = "parameter-color-field";
+ const colorControl = document.createElement("span");
+ colorControl.className = "parameter-color";
+ colorControl.dataset.open = "false";
+ const swatch = document.createElement("span");
+ swatch.className = "parameter-color-swatch";
+ const picker = document.createElement("input");
+ picker.type = "color";
+ picker.className = "parameter-color-native";
+ picker.setAttribute("aria-label", `${label} picker`);
+ picker.title = label;
+ const exact = /^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(initial);
+ picker.value = exact ? initial.slice(0, 7) : "#000000";
+ swatch.style.background = exact ? initial : "transparent";
+ const value = document.createElement("input");
+ value.type = "text";
+ value.className = "parameter-value parameter-color-value";
+ value.value = initial;
+ value.setAttribute("aria-label", label);
+ value.spellcheck = false;
+ const alpha = exact && initial.length === 9 ? initial.slice(7) : "";
+ const replacement = (): string => `${picker.value.toUpperCase()}${alpha}`;
+ const close = (): void => {
+ if (openColorPicker?.root === colorControl) openColorPicker = undefined;
+ colorControl.dataset.open = "false";
+ picker.blur();
+ };
+ picker.addEventListener("click", (event) => {
+ if (openColorPicker?.root === colorControl) {
+ event.preventDefault();
+ close();
+ return;
+ }
+ openColorPicker?.close();
+ openColorPicker = { root: colorControl, close };
+ colorControl.dataset.open = "true";
+ });
+ picker.addEventListener("input", () => {
+ swatch.style.background = picker.value;
+ value.value = replacement();
+ if (draft) change(replacement());
+ });
+ picker.addEventListener("change", () => {
+ const next = replacement();
+ swatch.style.background = picker.value;
+ value.value = next;
+ close();
+ change(next);
+ });
+ 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";
+ change(next);
+ });
+ colorControl.append(swatch, picker);
+ field.append(colorControl, value);
+ return field;
+}
+
+function fieldLabel(name: string): string {
+ return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+
+function blankValue(schema: ValueSchema): CanonicalValue {
+ if (schema.kind === "string") return "";
+ if (schema.kind === "number" || schema.kind === "null" || schema.kind === "literal" || schema.kind === "oneOf") return null;
+ if (schema.kind === "boolean") return false;
+ if (schema.kind === "array") return [];
+ if (schema.kind === "object") return Object.fromEntries(Object.entries(schema.fields)
+ .filter(([, field]) => field.optional !== true)
+ .map(([name, field]) => [name, blankValue(field.schema)]));
+ return null;
+}
+
+function scalarDraftControl(
+ label: string,
+ schema: ValueSchema,
+ held: CanonicalValue | undefined,
+ change: (value: CanonicalValue) => void,
+): HTMLElement {
+ if (schema.kind === "string" && schema.format === "color") {
+ return colorValueControl(label, typeof held === "string" ? held : "", change, true);
+ }
+ const input = document.createElement("input");
+ input.className = "parameter-value parameter-structured-value";
+ input.setAttribute("aria-label", label);
+ input.spellcheck = false;
+ if (schema.kind === "boolean") {
+ input.type = "checkbox";
+ input.checked = held === true;
+ input.addEventListener("change", () => change(input.checked));
+ return input;
+ }
+ input.type = "text";
+ if (schema.kind === "number") input.inputMode = "decimal";
+ input.value = held === undefined || held === null ? "" : textValue(held);
+ input.addEventListener("input", () => {
+ if (schema.kind === "number") {
+ const number = Number(input.value);
+ change(input.value.trim().length === 0 || !Number.isFinite(number) ? null : number);
+ } else {
+ change(input.value);
+ }
+ });
+ return input;
+}
+
+function recordDraftControl(
+ schema: Extract<ValueSchema, { readonly kind: "object" }>,
+ held: CanonicalValue,
+ change: (value: CanonicalValue) => void,
+): HTMLElement {
+ let record = (held !== null && !Array.isArray(held) && typeof held === "object"
+ ? held
+ : {}) as Readonly<Record<string, CanonicalValue>>;
+ const fields = document.createElement("div");
+ fields.className = "parameter-record-fields";
+ for (const [name, field] of Object.entries(schema.fields)) {
+ const row = document.createElement("label");
+ row.className = "parameter-record-field";
+ const copy = document.createElement("span");
+ copy.textContent = fieldLabel(name);
+ row.append(copy, scalarDraftControl(fieldLabel(name), field.schema, record[name], (next) => {
+ record = { ...record, [name]: next };
+ change(record);
+ }));
+ fields.append(row);
+ }
+ return fields;
+}
+
+function structuredControl(entityId: string, parameter: Clip["inspector"][number]): HTMLElement {
+ const schema = parameter.schema;
+ const shell = document.createElement("div");
+ shell.className = "parameter-structured";
+ if (schema === undefined || (schema.kind !== "array" && schema.kind !== "object")) return shell;
+ let draft = structuredClone(parameter.value);
+ let refreshDecisions = (): void => {};
+
+ const valid = (): boolean => {
+ try {
+ validateParameterValue(draft, schema, parameter.label);
+ return true;
+ } catch {
+ return false;
+ }
+ };
+
+ const render = (): void => {
+ shell.replaceChildren();
+ const summary = document.createElement("div");
+ summary.className = "parameter-structured-summary";
+ const count = document.createElement("span");
+ count.textContent = schema.kind === "array" && Array.isArray(draft)
+ ? `${draft.length} ${draft.length === 1 ? "item" : "items"}`
+ : "Structured value";
+ summary.append(count);
+ shell.append(summary);
+
+ if (schema.kind === "array") {
+ const list = Array.isArray(draft) ? draft : [];
+ const items = document.createElement("div");
+ items.className = "parameter-list-items";
+ list.forEach((item, index) => {
+ const row = document.createElement("div");
+ row.className = `parameter-list-item${schema.items.kind === "object" ? " record" : ""}`;
+ const editor = schema.items.kind === "object"
+ ? recordDraftControl(schema.items, item, (next) => {
+ const current = Array.isArray(draft) ? draft : [];
+ draft = current.map((candidate, heldIndex) => heldIndex === index ? next : candidate);
+ refreshDecisions();
+ })
+ : scalarDraftControl(`${parameter.label} ${index + 1}`, schema.items, item, (next) => {
+ const current = Array.isArray(draft) ? draft : [];
+ draft = current.map((candidate, heldIndex) => heldIndex === index ? next : candidate);
+ refreshDecisions();
+ });
+ const actions = document.createElement("span");
+ actions.className = "parameter-list-actions";
+ const move = (offset: number): void => {
+ const reordered = [...(Array.isArray(draft) ? draft : [])];
+ const [moving] = reordered.splice(index, 1);
+ reordered.splice(index + offset, 0, moving!);
+ draft = reordered;
+ render();
+ };
+ const up = document.createElement("button");
+ up.type = "button";
+ up.textContent = "↑";
+ up.title = "Move up";
+ up.disabled = index === 0;
+ up.addEventListener("click", () => move(-1));
+ const down = document.createElement("button");
+ down.type = "button";
+ down.textContent = "↓";
+ down.title = "Move down";
+ down.disabled = index === list.length - 1;
+ down.addEventListener("click", () => move(1));
+ const remove = document.createElement("button");
+ remove.type = "button";
+ remove.innerHTML = icon("minus");
+ remove.title = "Remove item";
+ remove.disabled = schema.minItems !== undefined && list.length <= schema.minItems;
+ remove.addEventListener("click", () => {
+ const current = Array.isArray(draft) ? draft : [];
+ draft = current.filter((_, heldIndex) => heldIndex !== index);
+ render();
+ });
+ actions.append(up, down, remove);
+ row.append(editor, actions);
+ items.append(row);
+ });
+ shell.append(items);
+ } else {
+ shell.append(recordDraftControl(schema, draft, (next) => {
+ draft = next;
+ refreshDecisions();
+ }));
+ }
+
+ const footer = document.createElement("div");
+ footer.className = "parameter-structured-footer";
+ if (schema.kind === "array") {
+ const list = Array.isArray(draft) ? draft : [];
+ const add = document.createElement("button");
+ add.type = "button";
+ add.className = "parameter-structured-add";
+ add.innerHTML = `${icon("plus")}<span>Add ${schema.items.kind === "string" && schema.items.format === "color" ? "color" : "item"}</span>`;
+ add.disabled = schema.maxItems !== undefined && list.length >= schema.maxItems;
+ add.addEventListener("click", () => {
+ const current = Array.isArray(draft) ? draft : [];
+ draft = [...current, blankValue(schema.items)];
+ render();
+ });
+ footer.append(add);
+ }
+ const decisions = document.createElement("span");
+ decisions.className = "parameter-structured-decisions";
+ const reset = document.createElement("button");
+ reset.type = "button";
+ reset.textContent = "Reset";
+ reset.disabled = sameValue(draft, parameter.value);
+ reset.addEventListener("click", () => {
+ draft = structuredClone(parameter.value);
+ render();
+ });
+ const apply = document.createElement("button");
+ apply.type = "button";
+ apply.className = "primary";
+ apply.textContent = "Apply";
+ apply.addEventListener("click", () => commitControl(entityId, parameter, draft));
+ refreshDecisions = () => {
+ reset.disabled = sameValue(draft, parameter.value);
+ apply.disabled = reset.disabled || !valid();
+ };
+ refreshDecisions();
+ decisions.append(reset, apply);
+ footer.append(decisions);
+ shell.append(footer);
+ };
+ render();
+ return shell;
+}
+
+function parameterControl(entityId: string, parameter: Clip["inspector"][number]): HTMLElement {
+ const row = document.createElement("div");
+ row.className = `parameter-row parameter-editable control-${parameter.control}`;
const name = document.createElement("span");
name.className = "parameter-label";
name.textContent = parameter.label;
name.title = parameter.summary ?? parameter.label;
- const source = document.createElement("small");
- source.className = "parameter-source";
- source.textContent = `${parameter.language.toUpperCase()} · ${parameter.source.path}:${parameter.source.range.start}`;
- source.title = parameter.disabledReason ?? parameter.source.preimage;
- const value = parameter.writable
- ? document.createElement(parameter.control === "select" ? "select" : "input")
- : document.createElement("strong");
- value.className = "parameter-value";
- if (value instanceof HTMLInputElement) {
- value.type = parameter.control === "number" ? "number" : parameter.control === "boolean" ? "checkbox" : "text";
- if (value.type === "checkbox") value.checked = parameter.value === "true";
- else value.value = parameter.value;
+ const right = document.createElement("span");
+ right.className = "parameter-right parameter-control";
+ 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);
+ }));
+ } else if (parameter.control === "list" || parameter.control === "record") {
+ right.append(structuredControl(entityId, parameter));
+ } else {
+ 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);
value.dataset.parameterId = parameter.id;
- value.title = parameter.source.preimage;
+ value.title = parameter.summary ?? parameter.label;
value.addEventListener("change", () => {
- void writeParameter(entityId, parameter, value.type === "checkbox" ? String(value.checked) : value.value);
+ 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);
+ } else {
+ commitControl(entityId, parameter, value.value);
+ }
});
- } else if (value instanceof HTMLSelectElement) {
- for (const option of parameter.options ?? []) {
- const item = document.createElement("option");
- item.value = option;
- item.textContent = option;
- item.selected = option === parameter.value;
- value.append(item);
- }
- value.addEventListener("change", () => void writeParameter(entityId, parameter, value.value));
- } else {
- value.textContent = parameter.value;
- value.title = parameter.disabledReason ?? parameter.source.preimage;
+ right.append(value);
}
- const suffix = parameter.unit === undefined ? "" : ` ${parameter.unit}`;
- const right = document.createElement("span");
- right.className = "parameter-right";
- right.append(value);
- if (suffix.length > 0) {
+ if (parameter.unit !== undefined) {
const unit = document.createElement("small");
- unit.textContent = suffix;
+ unit.textContent = parameter.unit;
right.append(unit);
}
row.append(name, right);
- if (parameter.group === undefined) row.append(source);
- else row.title = `${parameter.summary ?? parameter.label}\n${source.textContent}`;
- if (!parameter.writable) row.title = parameter.disabledReason ?? "Read-only source parameter";
+ row.title = parameter.summary ?? parameter.label;
return row;
}
-function parameterGroups(entityId: string, parameters: readonly Clip["parameters"][number][]): readonly HTMLElement[] {
- type StudioParameterValue = Clip["parameters"][number];
- const groups = new Map<string, StudioParameterValue[]>();
- for (const parameter of parameters) {
- const key = parameter.group === undefined
- ? `source\u0000${parameter.language}\u0000${parameter.source.path}`
- : `recipe\u0000${parameter.group}\u0000${parameter.section ?? "parameters"}`;
+function parameterGroups(entityId: string, fields: readonly Clip["inspector"][number][]): readonly HTMLElement[] {
+ const groups = new Map<string, Clip["inspector"][number][]>();
+ for (const field of fields) {
+ const key = `${field.section.id}\u0000${field.section.label}`;
const held = groups.get(key) ?? [];
- held.push(parameter);
+ held.push(field);
groups.set(key, held);
}
return [...groups].map(([key, values]) => {
- const [kind, first = "", second = ""] = key.split("\u0000");
- const title = kind === "recipe"
- ? `${first.slice(0, 1).toUpperCase()}${first.slice(1)} · ${second.replaceAll("-", " ")}`
- : second.length === 0 ? first.toUpperCase() : `${first.toUpperCase()} · ${second}`;
- return group(title, values.map((parameter) => parameterControl(entityId, parameter)), "parameter-group");
+ const [, label = ""] = key.split("\u0000");
+ return group(label, values.map((parameter) => parameterControl(entityId, parameter)), "parameter-group inspector-field-group");
});
}
-const operationLabels: Readonly<Record<Clip["editHandles"][number]["gesture"], string>> = {
- move: "Move",
- "trim-start": "Trim start",
- "trim-end": "Trim end",
-};
-
-const operationCoordinateLabels: Readonly<Record<NonNullable<Clip["editHandles"][number]["coordinate"]>, string>> = {
- "program-frame": "program frames",
- "semantic-anchor": "semantic anchors",
- "source-frame": "source frames",
- "canvas-pixel": "canvas pixels",
- "normalized-progress": "normalized progress",
-};
-
-function operationGroups(handles: readonly Clip["editHandles"][number][]): readonly HTMLElement[] {
- if (handles.length === 0) return [];
- return [group("Timeline operations", handles.map((handle) => {
- const node = document.createElement("div");
- node.className = `operation-row${handle.enabled ? " operation-enabled" : " operation-disabled"}`;
- const copy = document.createElement("span");
- copy.className = "operation-copy";
- const label = document.createElement("strong");
- label.className = "operation-label";
- label.textContent = operationLabels[handle.gesture];
- const detail = document.createElement("small");
- detail.className = "operation-detail";
- const coordinate = handle.coordinate === undefined ? "" : operationCoordinateLabels[handle.coordinate];
- const snap = handle.snapTo === undefined || handle.snapTo.length === 0
- ? ""
- : `snap ${handle.snapTo.join(" · ")}`;
- const source = handle.sources === undefined || handle.sources.length === 0
- ? ""
- : handle.sources.map((item) => `${item.role} → ${item.source.path}:${item.source.range.start}`).join(" · ");
- detail.textContent = [coordinate, snap, source].filter((value) => value.length > 0).join(" · ");
- copy.append(label, detail);
- const state = document.createElement("strong");
- state.className = "operation-state";
- state.textContent = handle.enabled ? "Timeline" : "—";
- node.title = handle.disabledReason
- ?? (handle.enabled ? "按时间线把手操作,成功后会回写源文件。" : "当前实体没有可逆的 Studio 写回。" );
- node.append(copy, state);
- return node;
- }), "operation-group")];
-}
-
let parameterWriteState: "" | "Saving" | "Saved" | "Failed" = "";
-async function writeParameter(entityId: string, parameter: Clip["parameters"][number], replacement: string): Promise<void> {
+async function writeParameter(entityId: string, parameter: Clip["inspector"][number], replacement: CanonicalValue): Promise<void> {
const state = store.current();
- if (state === undefined || !parameter.writable) return;
+ if (state === undefined) return;
parameterWriteState = "Saving";
status.textContent = parameterWriteState;
status.className = "status saving";
@@ -290,162 +700,108 @@ function renderInspector(snapshot: StudioSnapshot, clipId: string | undefined):
const clip = clipId === undefined ? undefined : store.clip(clipId);
if (clip === undefined) {
+ defaultWorkspaceHeading();
const fps = snapshot.space.frameRate.numerator / snapshot.space.frameRate.denominator;
- const hero = document.createElement("div");
- hero.className = "selection-hero overview-hero";
- hero.innerHTML = `
- <span class="selection-icon" data-selection-icon></span>
- <div class="selection-title"><strong></strong><small></small></div>
- <span class="selection-kind">Project</span>`;
- setIcon(hero.querySelector("[data-selection-icon]")!, "preview");
- hero.querySelector("strong")!.textContent = snapshot.source.path.split(/[\\/]/u).at(-1) ?? snapshot.source.path;
- hero.querySelector("small")!.textContent = `${snapshot.tracks.length} tracks · ${snapshot.source.files.length} source files`;
- inspector.replaceChildren(hero,
+ inspector.replaceChildren(
+ group("Project", [
+ property("Author", snapshot.source.path, "property-code"),
+ property("Run", snapshot.run.path, "property-code"),
+ property("Sources", `${snapshot.source.files.length} referenced files`),
+ property("Tracks", String(snapshot.tracks.length), "property-number"),
+ ]),
group("Canvas", [
- property("Size", `${snapshot.space.canvasWidth} × ${snapshot.space.canvasHeight}`, "property-number"),
+ property("Resolution", `${snapshot.space.canvasWidth} × ${snapshot.space.canvasHeight}`, "property-number"),
+ property("Aspect ratio", aspectRatio(snapshot.space.canvasWidth, snapshot.space.canvasHeight), "property-number"),
+ ]),
+ group("Timeline", [
+ property("Duration", `${snapshot.space.durationSec.toFixed(2)} s`, "property-number"),
property("Frame rate", `${fps.toFixed(Number.isInteger(fps) ? 0 : 2)} fps`, "property-number"),
- property("Duration", `${snapshot.space.durationSec.toFixed(2)}s`, "property-number"),
property("Frames", String(snapshot.space.frameCount), "property-number"),
]),
- group("Source", [
- property("Author", snapshot.source.path, "property-wide property-code"),
- property("Run", snapshot.run.path, "property-wide property-code"),
- property("Closure", `${snapshot.source.files.length} referenced files`),
- ]),
- group("Build intent", [
+ group("Build", [
property("Targets", snapshot.run.targets
.map((target) => target.split("::output::").at(-1) ?? target)
- .join(", ") || "—", "property-wide property-code"),
+ .join(", ") || "—", "property-code"),
property("Candidates", String(snapshot.run.satisfactions.length), "property-number"),
]),
);
return;
}
-
- const fps = snapshot.space.frameRate.numerator / snapshot.space.frameRate.denominator;
- const durationFrames = clip.endFrameExclusive - clip.startFrame;
- const track = snapshot.tracks.find((item) => item.clips.some((candidate) => candidate.id === clip.id));
- const hero = document.createElement("div");
- hero.className = "selection-hero";
- hero.innerHTML = `
- <span class="selection-icon" data-selection-icon></span>
- <div class="selection-title"><strong></strong><small></small></div>
- <span class="selection-kind"></span>`;
- setIcon(hero.querySelector("[data-selection-icon]")!, track?.binding.icon ?? "component");
- hero.querySelector(".selection-kind")!.textContent = track === undefined
- ? "Track"
- : `${track.binding.family} · ${track.binding.facet}`;
- hero.querySelector("strong")!.textContent = clip.display.title;
- hero.querySelector("small")!.textContent = track?.label ?? "Visual track";
-
- const timing = group("Timing", [
- property("Start", `${clip.startFrame}f`, "property-number"),
- property("End", `${clip.endFrameExclusive}f`, "property-number"),
- property("Duration", `${durationFrames}f`, "property-number"),
- property("Seconds", `${(durationFrames / fps).toFixed(2)}s`, "property-number"),
- ]);
- const placement = group("Placement", [
- property("Track", track?.label ?? "—", "property-wide"),
- property("Type", track === undefined ? clip.presentation.entity : `${track.binding.family} / ${track.binding.facet}`),
- property("Item", clip.authoredId, "property-wide property-code"),
- ]);
- const source = clip.temporal === undefined ? undefined : group("Binding", [
- property("Source", `${clip.temporal.source.kind}${clip.temporal.source.id === undefined ? "" : ` · ${clip.temporal.source.id}`}`, "property-wide property-code"),
- ...(clip.temporal.projection === undefined ? []
- : clip.temporal.projection.kind === "point"
- ? [property("At", clip.temporal.projection.expression, "property-wide property-code")]
- : [
- property("From", clip.temporal.projection.startExpression, "property-wide property-code"),
- property("To", clip.temporal.projection.endExpression, "property-wide property-code"),
- ]),
- ]);
- const provenance = track === undefined ? undefined : group("Provenance", [
- property("Output", track.provenance.output, "property-wide property-code"),
- ...(track.provenance.candidateId === undefined ? [] : [
- property("Candidate", track.provenance.candidateId, "property-wide property-code"),
- ]),
- property("Status", track.provenance.status),
- ]);
- const operations = operationGroups(clip.editHandles);
- const parameters = parameterGroups(clip.id, clip.parameters);
- inspector.replaceChildren(hero, placement, timing, ...operations, ...parameters,
- ...(source === undefined ? [] : [source]), ...(provenance === undefined ? [] : [provenance]));
+ const domains = domainOrder.filter((domain) => clip.inspector.some((field) => field.domain === domain));
+ if (domains.length === 0) {
+ defaultWorkspaceHeading();
+ const empty = document.createElement("div");
+ empty.className = "inspector-empty";
+ empty.textContent = "No adjustable parameters";
+ inspector.replaceChildren(empty);
+ return;
+ }
+ const remembered = inspectorDomainByEntity.get(clip.id);
+ const activeDomain = remembered !== undefined && domains.includes(remembered) ? remembered : domains[0]!;
+ inspectorDomainByEntity.set(clip.id, activeDomain);
+ inspectorHeading(clip.id, domains, activeDomain, () => renderInspector(snapshot, clip.id));
+
+ const domainFields = clip.inspector.filter((field) => field.domain === activeDomain);
+ const pages = new Map<string, { readonly label: string; readonly fields: typeof domainFields }>();
+ for (const field of domainFields) {
+ const id = field.page?.id ?? "default";
+ const page = pages.get(id) ?? { label: field.page?.label ?? "", fields: [] };
+ pages.set(id, { ...page, fields: [...page.fields, field] });
+ }
+ const pageIds = [...pages.keys()];
+ const memoryKey = `${clip.id}:${activeDomain}`;
+ const rememberedPage = inspectorPageByEntity.get(memoryKey);
+ const activePage = rememberedPage !== undefined && pages.has(rememberedPage) ? rememberedPage : pageIds[0]!;
+ inspectorPageByEntity.set(memoryKey, activePage);
+ const page = pages.get(activePage)!;
+ const subtabs = document.createElement("div");
+ subtabs.className = "inspector-subtabs";
+ if (pageIds.length > 1) {
+ subtabs.append(...pageIds.map((id) => {
+ const button = document.createElement("button");
+ button.type = "button";
+ button.className = `inspector-subtab${id === activePage ? " active" : ""}`;
+ const label = document.createElement("span");
+ label.textContent = pages.get(id)?.label ?? id;
+ button.append(label);
+ button.addEventListener("click", () => {
+ inspectorPageByEntity.set(memoryKey, id);
+ renderInspector(snapshot, clip.id);
+ });
+ return button;
+ }));
+ }
+ inspector.replaceChildren(...(pageIds.length > 1 ? [subtabs] : []), ...parameterGroups(clip.id, page.fields));
}
function renderSemanticInspector(snapshot: StudioSnapshot, segmentId: string): void {
const segment = snapshot.semantic.segments.find((item) => item.id === segmentId);
if (segment === undefined) { inspector.replaceChildren(); return; }
- const fps = snapshot.space.frameRate.numerator / snapshot.space.frameRate.denominator;
- const durationFrames = segment.endFrameExclusive - segment.startFrame;
- const hero = document.createElement("div");
- hero.className = "selection-hero";
- hero.innerHTML = `
- <span class="selection-icon" data-selection-icon></span>
- <div class="selection-title"><strong></strong><small></small></div>
- <span class="selection-kind"></span>`;
- setIcon(hero.querySelector("[data-selection-icon]")!, snapshot.semantic.presentation.icon);
- hero.querySelector("strong")!.textContent = segment.id;
- hero.querySelector("small")!.textContent = "Semantic take";
- hero.querySelector(".selection-kind")!.textContent = snapshot.semantic.presentation.label ?? "Semantic";
- inspector.replaceChildren(hero, group("Timing", [
- property("Start", `${segment.startFrame}f`, "property-number"),
- property("End", `${segment.endFrameExclusive}f`, "property-number"),
- property("Duration", `${durationFrames}f`, "property-number"),
- property("Seconds", `${(durationFrames / fps).toFixed(2)}s`, "property-number"),
- ]));
+ defaultWorkspaceHeading();
+ const empty = document.createElement("div");
+ empty.className = "inspector-empty";
+ empty.textContent = "No adjustable parameters";
+ inspector.replaceChildren(empty);
}
function renderSemanticSelectionInspector(snapshot: StudioSnapshot, selectionId: string): void {
const selection = snapshot.semantic.selections.find((item) => item.id === selectionId);
if (selection === undefined) { inspector.replaceChildren(); return; }
- const fps = snapshot.space.frameRate.numerator / snapshot.space.frameRate.denominator;
- const durationFrames = selection.endFrameExclusive - selection.startFrame;
- const source = snapshot.script?.selections.find((item) => item.id === selectionId);
- const hero = document.createElement("div");
- hero.className = "selection-hero";
- hero.innerHTML = `
- <span class="selection-icon" data-selection-icon></span>
- <div class="selection-title"><strong></strong><small></small></div>
- <span class="selection-kind">Selection</span>`;
- setIcon(hero.querySelector("[data-selection-icon]")!, "link");
- hero.querySelector("strong")!.textContent = selection.id;
- hero.querySelector("small")!.textContent = "Author intent";
- inspector.replaceChildren(hero,
- group("Timing", [
- property("Start", `${selection.startFrame}f`, "property-number"),
- property("End", `${selection.endFrameExclusive}f`, "property-number"),
- property("Duration", `${durationFrames}f`, "property-number"),
- property("Seconds", `${(durationFrames / fps).toFixed(2)}s`, "property-number"),
- ]),
- ...(source === undefined ? [] : [group("Source", [
- property("Range", `${source.open.start}–${source.close.end}`, "property-wide property-code"),
- ])]),
- );
+ defaultWorkspaceHeading();
+ const empty = document.createElement("div");
+ empty.className = "inspector-empty";
+ empty.textContent = "Adjust on the timeline";
+ inspector.replaceChildren(empty);
}
function renderSemanticMomentInspector(snapshot: StudioSnapshot, momentId: string): void {
const moment = snapshot.semantic.moments.find((item) => item.id === momentId);
if (moment === undefined) { inspector.replaceChildren(); return; }
- const fps = snapshot.space.frameRate.numerator / snapshot.space.frameRate.denominator;
- const source = snapshot.script?.moments.find((item) => item.id === momentId);
- const hero = document.createElement("div");
- hero.className = "selection-hero";
- hero.innerHTML = `
- <span class="selection-icon" data-selection-icon></span>
- <div class="selection-title"><strong></strong><small></small></div>
- <span class="selection-kind">Moment</span>`;
- setIcon(hero.querySelector("[data-selection-icon]")!, "moment");
- hero.querySelector("strong")!.textContent = moment.id;
- hero.querySelector("small")!.textContent = "Author intent";
- inspector.replaceChildren(hero,
- group("Timing", [
- property("Frame", `${moment.frame}f`, "property-number"),
- property("Seconds", `${(moment.frame / fps).toFixed(2)}s`, "property-number"),
- ]),
- ...(source === undefined ? [] : [group("Source", [
- property("Range", `${source.range.start}–${source.range.end}`, "property-wide property-code"),
- ])]),
- );
+ defaultWorkspaceHeading();
+ const empty = document.createElement("div");
+ empty.className = "inspector-empty";
+ empty.textContent = "Adjust on the timeline";
+ inspector.replaceChildren(empty);
}
// The word being spoken at the playhead, which is the point of carrying token
@@ -575,23 +931,24 @@ window.addEventListener("keydown", (event) => {
if (state === undefined || event.metaKey || event.ctrlKey || event.altKey) return;
// Space is the transport everywhere else; typing in a field is not transport.
const target = event.target instanceof Element ? event.target : undefined;
- const editing = target?.closest("input, textarea, select") !== null && target !== undefined;
- if (event.key === " " && !editing) {
+ const editing = target?.closest("input, textarea, select, [contenteditable=true], .parameter-control") !== null && target !== undefined;
+ if (editing) return;
+ if (event.key === " ") {
stage.toggle();
event.preventDefault();
return;
}
- if (!editing && (event.key === "-" || event.key === "_")) {
+ if (event.key === "-" || event.key === "_") {
timeline.zoomOut();
event.preventDefault();
return;
}
- if (!editing && (event.key === "=" || event.key === "+")) {
+ if (event.key === "=" || event.key === "+") {
timeline.zoomIn();
event.preventDefault();
return;
}
- if (!editing && (event.key === "\\" || event.key.toLowerCase() === "f")) {
+ if (event.key === "\\" || event.key.toLowerCase() === "f") {
timeline.fit();
event.preventDefault();
return;
diff --git a/packages/studio/test/parameters.test.ts b/packages/studio/test/parameters.test.ts
index 46f6054e..5fe2d5e5 100644
--- a/packages/studio/test/parameters.test.ts
+++ b/packages/studio/test/parameters.test.ts
@@ -9,7 +9,8 @@ import type {
import { projectedWindowTimelineEdits } from "@hypit/studio-adapter";
import type { MarkupSurfaceRegistryLike, RegisteredSurface } from "@hypit/markup";
-import { parametersForDraft, resolveTimelineEditHandles } from "../src/parameters.js";
+import { inspectorFieldsForBindings, resolveTimelineEditHandles, sourceBindingsForDraft } from "../src/parameters.js";
+import { serializeParameterValue, validateParameterValue } from "../src/parameter-values.js";
const semantic: StudioSemanticTimeline = {
presentation: {
@@ -37,6 +38,13 @@ const semantic: StudioSemanticTimeline = {
provenance: { output: "speech", origin: "run", status: "resolved", errors: [] },
};
+test("structured parameter values validate and serialize through the generic SVS path", () => {
+ const schema = { kind: "array", minItems: 1, items: { kind: "string", format: "color" } } as const;
+ assert.doesNotThrow(() => validateParameterValue(["#FF3F56", "#FFA72D"], schema, "Colors"));
+ assert.throws(() => validateParameterValue([], schema, "Colors"), /at least 1/u);
+ assert.equal(serializeParameterValue(["#FF3F56", "#FFA72D"], "svs"), '["#FF3F56","#FFA72D"]');
+});
+
test("timeline gestures resolve through the shared Selection identity", () => {
const temporal: StudioTemporalLineage = {
source: { kind: "selection", id: "claim" },
@@ -98,11 +106,11 @@ test("absolute Window edits use only the Companion's exact parameter vocabulary"
});
const parameters = [
{
- id: "from", name: "from", label: "From", control: "text" as const,
+ id: "from", binding: "from", name: "from",
value: "1f", language: "svml" as const, writable: true, source: source(0, 2),
},
{
- id: "until", name: "until", label: "Until", control: "text" as const,
+ id: "until", binding: "until", name: "until",
value: "20f", language: "svml" as const, writable: true, source: source(3, 6),
},
];
@@ -134,7 +142,7 @@ test("absolute Window edits use only the Companion's exact parameter vocabulary"
test("parameter Source paths stay relative to the author workspace", () => {
const text = "start=\"1f\"";
- const parameters = parametersForDraft({
+ const parameters = sourceBindingsForDraft({
root: "/workspace",
files: [{ path: "/workspace/main.svml", text, language: "svml" }],
placement: {
@@ -164,8 +172,9 @@ test("parameter Source paths stay relative to the author workspace", () => {
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">
- caption.alt { x: 0.4; handoff: overlap; }
+ caption.alt { x: 0.4; handoff: overlap; colors: ["#FF3F56", "#FFA72D"]; }
</sheet>`;
+ const colors = { kind: "array", minItems: 1, items: { kind: "string", format: "color" } } as const;
const placement = (input: {
id: string;
module: string;
@@ -198,6 +207,7 @@ test("a derived entity follows its actual Style and Companion-owned Recipe prese
recipe: [
{ name: "x", required: true, summary: "Horizontal position" },
{ name: "handoff", required: false, summary: "Cue handoff", values: ["cut", "overlap"] },
+ { name: "colors", required: false, summary: "Ordered colors", schema: colors },
],
}] },
handler: () => ({ records: [], components: [], fragments: [], exports: [] }),
@@ -209,7 +219,13 @@ test("a derived entity follows its actual Style and Companion-owned Recipe prese
surfaces() { return [surface]; },
};
- const parameters = parametersForDraft({
+ const draft = {
+ id: "captions:cue:2", authoredId: "captions", presentId: "cue:2", display: { title: "cue:2", layers: [] },
+ startFrame: 0, endFrameExclusive: 10, stackOrder: 70,
+ elementRange: track.range,
+ parameterReferences: { program: "alternate-caption" },
+ } as const;
+ const parameters = sourceBindingsForDraft({
root: "/workspace",
files: [
{ path: "main.svml", text: main, language: "svml", imports: [{ alias: "recipes", source: "./recipes.svs" }] },
@@ -217,30 +233,50 @@ test("a derived entity follows its actual Style and Companion-owned Recipe prese
],
placement: track,
placements: [track, style],
- draft: {
- id: "captions:cue:2", authoredId: "captions", presentId: "cue:2", display: { title: "cue:2", layers: [] },
- startFrame: 0, endFrameExclusive: 10, stackOrder: 70,
- elementRange: track.range,
- parameterReferences: { program: "alternate-caption" },
- },
+ draft,
declarations: [{
- name: "program", label: "Program", writable: false,
+ name: "program",
recipe: {
through: ["recipe"],
- parameters: [
- { name: "x", group: "where", section: "region" },
- { name: "handoff", group: "when", section: "envelope" },
+ bindings: [
+ { name: "x" },
+ { name: "handoff" },
+ { name: "colors", schema: colors },
+ { name: "fallback-colors", schema: colors, fallback: ["#000000"] },
],
},
}],
- surfaces,
});
+ const inspector = inspectorFieldsForBindings(draft, parameters, [
+ {
+ binding: "program.x", label: "X", domain: "where", page: { id: "placement", label: "Placement" },
+ section: { id: "region", label: "Region" }, control: "number",
+ },
+ {
+ binding: "program.handoff", label: "Handoff", domain: "when", page: { id: "cue", label: "Cue" },
+ section: { id: "envelope", label: "Envelope" }, control: "select", options: ["cut", "overlap"],
+ },
+ {
+ binding: "program.colors", label: "Colors", domain: "how", page: { id: "paint", label: "Paint" },
+ section: { id: "palette", label: "Palette" },
+ },
+ {
+ binding: "program.fallback-colors", label: "Fallback Colors", domain: "how", page: { id: "paint", label: "Paint" },
+ section: { id: "palette", label: "Palette" },
+ },
+ ]);
- assert.deepEqual(parameters.map(({ name, group, section, control, options }) => ({
- name, group, section, control, options,
+ assert.deepEqual(inspector.map(({ binding, domain, section, control, options }) => ({
+ binding, domain, section: section.id, control, options,
})), [
- { name: "x", group: "where", section: "region", control: "number", options: undefined },
- { name: "handoff", group: "when", section: "envelope", control: "select", options: ["cut", "overlap"] },
+ { binding: "program.x", domain: "where", section: "region", control: "number", options: undefined },
+ { binding: "program.handoff", domain: "when", section: "envelope", control: "select", options: ["cut", "overlap"] },
+ { binding: "program.colors", domain: "how", section: "palette", control: "list", options: undefined },
+ { binding: "program.fallback-colors", domain: "how", section: "palette", control: "list", options: undefined },
]);
+ assert.deepEqual(inspector[2]?.value, ["#FF3F56", "#FFA72D"]);
+ assert.deepEqual(inspector[3]?.value, ["#000000"]);
+ assert.equal(inspector[3]?.source.preimage, "");
+ assert.match(inspector[3]?.source.prefix ?? "", /fallback-colors/u);
assert.ok(parameters.every((parameter) => parameter.source.path === "recipes.svs"));
});
diff --git a/packages/svs/README.md b/packages/svs/README.md
index 0b67172e..64442fe2 100644
--- a/packages/svs/README.md
+++ b/packages/svs/README.md
@@ -8,6 +8,17 @@ The SVS Frontend reads a `<sheet version="1">` containing named rule blocks and
not implement CSS selectors, cascade or inheritance. A consuming package validates a Recipe's
properties and lowers it into its own typed Program Record.
+Recipe values use the shared canonical value model: `null`, booleans, finite
+numbers and strings remain compact scalar values; lists and records use strict
+JSON array/object syntax. SVS only parses and serializes those shapes. The
+consuming domain package owns their schema and meaning.
+
+```svs
+ranking.column {
+ rank-colors: ["#ff3f56", "#ffa72d", "#eadc2a"];
+}
+```
+
Source import aliases are owned by Source Closure compilation. A rule `caption.alice` remains that
relative public export; importing it as `studio` exposes `studio.caption.alice` without changing the
Recipe Record identity.
diff --git a/packages/svs/src/format.ts b/packages/svs/src/format.ts
new file mode 100644
index 00000000..6be5cb83
--- /dev/null
+++ b/packages/svs/src/format.ts
@@ -0,0 +1,16 @@
+import type { CanonicalValue } from "@hypit/protocol";
+
+const BARE = /^[^\s;,\[\]{}"']+$/u;
+const NUMBER = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/u;
+
+/** Serialize one canonical value without knowing which component consumes it. */
+export function formatSvsValue(value: CanonicalValue): string {
+ if (value === null) return "null";
+ if (typeof value === "boolean" || typeof value === "number") return String(value);
+ if (typeof value === "string") {
+ return BARE.test(value) && value !== "null" && value !== "true" && value !== "false" && !NUMBER.test(value)
+ ? value
+ : JSON.stringify(value);
+ }
+ return JSON.stringify(value);
+}
diff --git a/packages/svs/src/index.ts b/packages/svs/src/index.ts
index db3cf472..fa42a51e 100644
--- a/packages/svs/src/index.ts
+++ b/packages/svs/src/index.ts
@@ -1,4 +1,5 @@
export { svsFrontendId, svsManifest, svsModuleRef, svsRecipeType } from "./manifest.js";
export { SvsSyntaxError, parseSvs } from "./parser.js";
+export { formatSvsValue } from "./format.js";
export { svsFrontend } from "./frontend.js";
export type * from "./types.js";
diff --git a/packages/svs/src/parser.ts b/packages/svs/src/parser.ts
index b82f52e4..db9d3416 100644
--- a/packages/svs/src/parser.ts
+++ b/packages/svs/src/parser.ts
@@ -73,6 +73,7 @@ function withoutComments(sourceName: string, text: string): string {
function closingBrace(text: string, start: number, limit: number): number {
let quote: "\"" | "'" | undefined;
let escaped = false;
+ let nested = 0;
for (let cursor = start; cursor < limit; cursor += 1) {
const character = text[cursor];
if (escaped) {
@@ -91,7 +92,14 @@ function closingBrace(text: string, start: number, limit: number): number {
quote = character;
continue;
}
- if (character === "}") return cursor;
+ if (character === "{") {
+ nested += 1;
+ continue;
+ }
+ if (character === "}") {
+ if (nested === 0) return cursor;
+ nested -= 1;
+ }
}
return -1;
}
@@ -137,9 +145,17 @@ function parseAttributes(
function parseValue(sourceName: string, text: string, offset: number): CanonicalValue {
const value = text.trim();
if (value.length === 0) fail(sourceName, "SVS_VALUE_EMPTY", "Recipe property value is empty.", offset);
+ if (value === "null") return null;
if (value === "true") return true;
if (value === "false") return false;
if (/^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/u.test(value)) return Number(value);
+ if (value.startsWith("[") || value.startsWith("{")) {
+ try {
+ return JSON.parse(value) as CanonicalValue;
+ } catch {
+ fail(sourceName, "SVS_VALUE_STRUCTURED", "Structured Recipe values must use JSON array/object syntax.", offset);
+ }
+ }
if (
(value.startsWith('"') && value.endsWith('"'))
|| (value.startsWith("'") && value.endsWith("'"))
diff --git a/packages/svs/test/source-closure.test.ts b/packages/svs/test/source-closure.test.ts
index 51c5e3a1..c0b6391d 100644
--- a/packages/svs/test/source-closure.test.ts
+++ b/packages/svs/test/source-closure.test.ts
@@ -20,6 +20,7 @@ import type {
TypedRecord,
} from "@hypit/protocol";
import {
+ formatSvsValue,
SvsSyntaxError,
parseSvs,
svsFrontend,
@@ -312,6 +313,19 @@ test("quoted Recipe values may contain Prompt punctuation without changing SVS s
assert.equal(sheet.recipes[0]?.value.properties.text, "first; second } /* literal */");
});
+test("SVS parses and serializes canonical arrays and objects as one Recipe value", () => {
+ const source = `<sheet version="1">
+ ranking.column {
+ colors: ["#FF3F56", "#FFA72D"];
+ rows: [{"id":"s","label":"S","color":"#EF4444"}];
+ }
+</sheet>`;
+ const recipe = parseSvs("structured.svs", source).recipes[0]!;
+ assert.deepEqual(recipe.value.properties.colors, ["#FF3F56", "#FFA72D"]);
+ assert.deepEqual(recipe.value.properties.rows, [{ id: "s", label: "S", color: "#EF4444" }]);
+ assert.equal(formatSvsValue(recipe.value.properties.colors!), '["#FF3F56","#FFA72D"]');
+});
+
test("SVS exposes exact property and value spans without inventing editor metadata", () => {
const source = `<sheet version="1">
caption.primary {
diff --git a/packages/typography-track-studio/src/index.ts b/packages/typography-track-studio/src/index.ts
index b12032f9..bd914728 100644
--- a/packages/typography-track-studio/src/index.ts
+++ b/packages/typography-track-studio/src/index.ts
@@ -1,21 +1,63 @@
import { typographyTrackMarkupSurfaces } from "@hypit/typography-track";
import type { TypographyTrackProgram } from "@hypit/typography-track";
-import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft, StudioRecipeParameterDeclaration } from "@hypit/studio-adapter";
+import type { StudioAdapter, StudioAdapterContext, StudioEntityDraft, StudioInspectorFieldDeclaration } from "@hypit/studio-adapter";
import { childEntities, projectedWindowTimelineEdits, requiredSurfaceValue, temporalLineageFor, textLayer } from "@hypit/studio-adapter";
-const typographyStyleRecipe: readonly StudioRecipeParameterDeclaration[] = (typographyTrackMarkupSurfaces
+const typographyProperties = (typographyTrackMarkupSurfaces
.find((surface) => surface.name === "style")?.vocabulary.attributes
- .find((attribute) => attribute.name === "recipe")?.recipe ?? []).map((property) => {
- const where = [
- "stack-order", "inline-size", "block-size", "padding", "align", "block-align", "wrap", "overflow",
- "max-lines", "minimum-scale", "clip", "columns", "column-gap", "point-anchor-x", "point-anchor-y",
- ].includes(property.name) || property.name.startsWith("path-");
- return {
- name: property.name,
- group: where ? "where" : "how",
- section: where ? "layout" : "typography",
- };
- });
+ .find((attribute) => attribute.name === "recipe")?.recipe ?? []);
+
+function title(name: string): string {
+ return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+
+function valuesFor(property: typeof typographyProperties[number]): readonly string[] | undefined {
+ return "values" in property ? property.values : undefined;
+}
+
+type TypographyPlacement = Pick<StudioInspectorFieldDeclaration, "domain" | "page" | "section">;
+
+function typographyPlace(domain: "where" | "how", page: string, section: string): TypographyPlacement {
+ const id = section.toLowerCase().replaceAll(" ", "-");
+ return { domain, page: { id: page.toLowerCase(), label: page }, section: { id, label: section } };
+}
+
+const typographyPlacement = new Map<string, TypographyPlacement>();
+function placeTypography(names: readonly string[], domain: "where" | "how", page: string, section: string): void {
+ for (const name of names) typographyPlacement.set(name, typographyPlace(domain, page, section));
+}
+
+placeTypography(["stack-order"], "where", "Layout", "Stacking");
+placeTypography([
+ "inline-size", "block-size", "padding", "align", "block-align", "wrap", "overflow", "max-lines",
+ "minimum-scale", "clip", "columns", "column-gap",
+], "where", "Layout", "Area");
+placeTypography(["point-anchor-inline", "point-anchor-block"], "where", "Layout", "Point");
+placeTypography([
+ "path-side", "path-orientation", "path-start-margin", "path-end-margin", "path-align", "path-reverse", "path-overflow",
+], "where", "Layout", "Path");
+placeTypography([
+ "size", "weight", "font-style", "line-height", "tracking", "word-spacing", "kerning", "synthesis", "language",
+ "direction", "writing-mode", "baseline-shift", "vertical-align", "tab-size", "indent", "paragraph-before",
+ "paragraph-after", "transform", "caps", "cjk-spacing", "punctuation-trim", "metric-edge",
+], "how", "Typography", "Typography");
+placeTypography(["fill"], "how", "Paint", "Fill");
+
+const typographyColorProperties = new Set(["fill"]);
+const typographyTextProperties = new Set(["language", "cjk-spacing", "punctuation-trim", "padding"]);
+
+const typographyInspector: readonly StudioInspectorFieldDeclaration[] = typographyProperties.map((property) => {
+ const placement = typographyPlacement.get(property.name);
+ if (placement === undefined) throw new Error(`Typography Studio has no explicit Inspector declaration for ${property.name}.`);
+ const options = valuesFor(property);
+ return {
+ binding: `style.${property.name}`, label: title(property.name), ...placement,
+ ...(property.summary === undefined ? {} : { summary: property.summary }),
+ control: options !== undefined ? "select" : typographyColorProperties.has(property.name) ? "color"
+ : typographyTextProperties.has(property.name) ? "text" : "number",
+ ...(options === undefined ? {} : { options }),
+ };
+});
function textOf(item: TypographyTrackProgram["items"][number]): string {
return item.document.paragraphs.map((paragraph) => paragraph.inlines
@@ -56,18 +98,19 @@ export const typographyTrackStudioAdapters: readonly StudioAdapter[] = [
output: { type: "VisualTrack", surface: "track", modules: ["@hypit/typography-track"] },
family: "text", tone: "violet", icon: "text",
timelineEdits: projectedWindowTimelineEdits({ start: "start", end: "end", duration: "for" }),
- parameters: [
- { name: "placement", label: "Placement", writable: false },
- { name: "content", label: "Content", writable: false },
- { name: "start", label: "Start", writable: true },
- { name: "end", label: "End", writable: true },
- { name: "for", label: "For", writable: true },
+ bindings: [
+ { name: "placement" },
+ { name: "content" },
+ { name: "start", writable: true },
+ { name: "end", writable: true },
+ { name: "for", writable: true },
{
- name: "style", label: "Style", writable: false,
- recipe: { through: ["recipe"], parameters: typographyStyleRecipe },
+ name: "style",
+ recipe: { through: ["recipe"], bindings: typographyProperties.map(({ name }) => ({ name })) },
},
- { name: "motion", label: "Motion", writable: false },
+ { name: "motion" },
],
+ inspector: typographyInspector,
requiredValues: ["program"], project: projectTypography,
lane: { heightPx: 48 },
},
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 181a0185..149bc35c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2657,6 +2657,9 @@ importers:
'@hypit/host':
specifier: workspace:*
version: link:../host
+ '@hypit/protocol':
+ specifier: workspace:*
+ version: link:../protocol
packages/svs:
dependencies: