@hypit/hypit 0.1.3 → 0.1.4

package/packages/studio/src/parameters.ts

@@ -238,8 +238,16 @@ function referencedParameters(input: {
   const file = sourceFor(input.root, target.sourcePath, input.files);
   if (file === undefined) return [];
   return input.declarations.flatMap((declaration) => {
+    const nestedPath = target.references[declaration.name];
+    const nested = nestedPath === undefined || declaration.referenced === undefined ? [] : referencedParameters({
+      root: input.root, files: input.files, draft: input.draft, placements: input.placements,
+      referenceName: `${input.referenceName}.${declaration.name}`,
+      referencePath: nestedPath,
+      ...(target.resolvedReferences[declaration.name] === undefined ? {} : { referenceRef: target.resolvedReferences[declaration.name] }),
+      declarations: declaration.referenced,
+    });
     const range = target.attributeValueRanges[declaration.name];
-    if (range === undefined) return [];
+    if (range === undefined) return nested;
     const preimage = file.text.slice(range.start, range.end);
     const reference = target.references[declaration.name];
     const value = reference === undefined ? (target.attributes[declaration.name] ?? preimage) : reference;
@@ -263,7 +271,7 @@ function referencedParameters(input: {
       ...(!writable
         ? { disabledReason: reference === undefined ? "该几何值由组件声明为只读。" : "引用由作者在 SVML 中绑定，面板不替换引用关系。" }
         : {}),
-    } satisfies StudioSourceBinding];
+    } satisfies StudioSourceBinding, ...nested];
   });
 }
 
@@ -484,7 +492,7 @@ export function resolveTimelineEditHandles(
     moveEffect?: "translate-window" | "move-start",
   ): StudioEditHandle => {
     const unavailable = affected.find(({ endpoint }) => endpoint.authority.kind === "fixed");
-    if (unavailable !== undefined) return disabled(gesture, "该端点由 Program 或 Segment 结构固定，不能从组件时间线反写。");
+    if (unavailable !== undefined) return disabled(gesture, "该时间表达未开放时间轴回写。");
     const projected: ({ readonly missing: string } | StudioEditSource)[] = [];
     for (const { endpoint, role } of affected) {
       if (endpoint.authority.kind !== "parameter") continue;
@@ -527,24 +535,15 @@ export function resolveTimelineEditHandles(
   }
   const start = { endpoint: projection.start, role: "start" as const };
   const end = { endpoint: projection.end, role: "end" as const };
-  const move = projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start"
-    ? [start]
-    : projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end"
-      ? [end]
-      : [start, end];
-  const trimStart = projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end"
-    ? [start]
-    : projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start"
-      ? [start, end]
-      : [start];
-  const trimEnd = projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start"
-    ? [end]
-    : projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end"
-      ? [start, end]
-      : [end];
+  if (projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start") {
+    return [handle("move", [start], "translate-window"), handle("trim-end", [end])];
+  }
+  if (projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end") {
+    return [handle("move", [end], "translate-window"), handle("trim-start", [start])];
+  }
   return [
-    handle("move", move, "translate-window"),
-    handle("trim-start", trimStart),
-    handle("trim-end", trimEnd),
+    handle("move", [start, end], "translate-window"),
+    handle("trim-start", [start]),
+    handle("trim-end", [end]),
   ];
 }

package/packages/studio/src/server.ts

@@ -15,12 +15,13 @@ import type { ServedFile } from "./compile.js";
 import type { StudioDomain } from "./domain.js";
 import type { StudioCompanionRegistry } from "./studio-registry.js";
 import { loadStudioRun } from "./run.js";
-import { serializeParameterValue, validateParameterValue } from "./parameter-values.js";
+import { parameterAuthorValue, parameterOption, serializeParameterValue, validateParameterValue } from "./parameter-values.js";
 import { readStudioSession } from "./session.js";
-import type { Range, StudioFailure, StudioLibraryView, StudioMutation, StudioSnapshot } from "./shared.js";
+import type { Range, StudioFailure, StudioLibraryRequest, StudioLibraryView, StudioMutation, StudioSnapshot } from "./shared.js";
 import { createStudioStoryboard } from "./storyboard.js";
 import type { StudioStoryboard } from "./storyboard.js";
 import { findSurfacePreview } from "./surface-preview.js";
+import { formatTemporalPointEdit, semanticGestureSpan } from "./temporal-edit.js";
 import { replaceSourceFiles } from "./source-transaction.js";
 
 export type StudioPluginOptions = {
@@ -93,8 +94,9 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
   const watchedFiles = new Set<string>();
   const storyboards = new Map<string, Promise<StudioStoryboard>>();
 
-  const readLibrary = async (before?: string): Promise<StudioLibraryView> => {
-    return await options.buildLibrary?.library(before) ?? {
+  const readLibrary = async (request: StudioLibraryRequest): Promise<StudioLibraryView> => {
+    return await options.buildLibrary?.library(request) ?? {
+      section: request.section,
       environment: options.workspaceRoot,
       tasks: [],
       artifacts: [],
@@ -271,7 +273,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
       throw new Error("A timeline target must use valid whole frames.");
     }
     if (temporal.kind === "window") {
-      if (mutation.gesture === "move"
+      if (mutation.gesture === "move" && handle.semantic?.kind !== "selection"
         && endFrameExclusive - startFrame !== clip.endFrameExclusive - clip.startFrame) {
         throw new Error("Move must preserve the Window duration.");
       }
@@ -287,6 +289,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
 
     const patches: Patch[] = [];
     const semanticTarget = mutation.target.semantic;
+    if (handle.semantic !== undefined && semanticTarget === undefined) throw new Error("A semantic edit requires explicit target anchors.");
     if (semanticTarget !== undefined) {
       if (handle.semantic?.kind !== semanticTarget.kind) {
         throw new Error(`Entity ${mutation.entityId} is not bound to a writable ${semanticTarget.kind}.`);
@@ -298,15 +301,9 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
         || script.narrativeId !== current.semantic.narrativeId) {
         throw new Error("The timeline entity and writable Script do not belong to the selected Narrative.");
       }
-      if (semanticTarget.kind === "selection") {
-        const startIndex = current.semantic.anchors.findIndex((anchor) => anchor.id === semanticTarget.startAnchorId);
-        const endIndex = current.semantic.anchors.findIndex((anchor) => anchor.id === semanticTarget.endAnchorId);
-        if (startIndex < 0 || endIndex < 0 || startIndex >= endIndex
-          || current.semantic.anchors[startIndex]!.frame >= current.semantic.anchors[endIndex]!.frame) {
-          throw new Error("A Selection must span two ordered semantic Anchors with positive time.");
-        }
-      } else if (!current.semantic.anchors.some((anchor) => anchor.id === semanticTarget.anchorId)) {
-        throw new Error(`Moment Anchor ${semanticTarget.anchorId} does not exist in the current semantic Candidate.`);
+      const projected = semanticGestureSpan(current.semantic.anchors, handle, semanticTarget);
+      if (projected === undefined || projected.startFrame !== startFrame || projected.endFrameExclusive !== endFrameExclusive) {
+        throw new Error("The semantic edit does not produce the requested timeline projection.");
       }
       const absolute = resolve(options.workspaceRoot, script.sourcePath);
       const source = await readFile(absolute, "utf8");
@@ -366,20 +363,15 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
       }
       return snapshot?.semantic?.moments.find((candidate) => candidate.id === id)?.frame;
     };
-    const projectedPointValue = (endpoint: StudioTemporalInstantProjection, desired: number): string => {
-      if (endpoint.reference === "absolute") return frame(desired);
-      const base = projectionBaseFrame(endpoint);
-      if (base === undefined) throw new Error(`The ${endpoint.reference} projection base is unavailable.`);
-      const offset = desired - base;
-      return offset === 0 ? endpoint.reference : `${endpoint.reference}${offset > 0 ? "+" : ""}${offset}f`;
-    };
+    const projectedPointValue = (endpoint: StudioTemporalInstantProjection, desired: number): string =>
+      formatTemporalPointEdit(endpoint.reference, desired, projectionBaseFrame(endpoint));
     const writeEndpoint = (
       endpoint: StudioTemporalInstantProjection,
       desired: number,
       role: "start" | "end",
     ): void => {
       if (desired === endpoint.frame) return;
-      if (endpoint.authority.kind === "fixed") throw new Error(`The ${role} endpoint is structurally fixed.`);
+      if (endpoint.authority.kind === "fixed") throw new Error(`The ${role} endpoint has no timeline write target.`);
       if (endpoint.authority.kind === "semantic") {
         if (semanticFrame(endpoint) !== desired) throw new Error(`The ${role} endpoint does not match its semantic Anchor.`);
         return;
@@ -413,20 +405,22 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
     if (parameter === undefined) {
       throw new Error(`Entity ${mutation.entityId} has no writable parameter ${mutation.parameterId}.`);
     }
+    const authorValue = parameterAuthorValue(parameter, mutation.value);
     if (parameter.schema !== undefined) {
-      validateParameterValue(mutation.value, parameter.schema, parameter.label);
+      validateParameterValue(authorValue, parameter.schema, parameter.label);
     } else if (parameter.control === "boolean" && typeof mutation.value !== "boolean") {
       throw new Error(`${parameter.label} expects true or false.`);
     } else if (parameter.control === "number" && (typeof mutation.value !== "number" || !Number.isFinite(mutation.value))) {
       throw new Error(`${parameter.label} expects a number.`);
-    } else if ((parameter.control === "text" || parameter.control === "color" || parameter.control === "select")
+    } else if ((parameter.control === "text" || parameter.control === "color")
       && typeof mutation.value !== "string") {
       throw new Error(`${parameter.label} expects text.`);
     }
-    if (parameter.options !== undefined && (typeof mutation.value !== "string" || !parameter.options.includes(mutation.value))) {
+    if (parameter.options !== undefined && !parameter.options.some(option => parameterOption(option).value === authorValue)) {
       throw new Error(`${parameter.label} does not accept ${mutation.value}.`);
     }
-    const encoded = serializeParameterValue(mutation.value, parameter.language);
+    if (parameter.control === "color") validateParameterValue(authorValue, { kind: "string", format: "color" }, parameter.label);
+    const encoded = serializeParameterValue(authorValue, parameter.language);
     const replacement = `${parameter.source.prefix ?? ""}${encoded}${parameter.source.suffix ?? ""}`;
     return replacement === parameter.source.preimage ? [] : [{
       ...parameter.source,
@@ -525,6 +519,28 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
           })();
           return;
         }
+        if (request.method === "PUT" && url.pathname === "/__studio/artifact-name") {
+          void (async () => {
+            try {
+              const chunks: Buffer[] = [];
+              for await (const chunk of request) chunks.push(Buffer.from(chunk));
+              const body = JSON.parse(Buffer.concat(chunks).toString("utf8")) as {
+                build?: unknown; output?: unknown; displayName?: unknown;
+              };
+              if (typeof body.build !== "string" || typeof body.output !== "string"
+                || (typeof body.displayName !== "string" && body.displayName !== null)) {
+                json(response, 400, { error: "Expected Build, Output and displayName" });
+                return;
+              }
+              if (options.buildLibrary === undefined) throw new Error("Result Repository is unavailable");
+              const displayName = await options.buildLibrary.renameArtifact(body.build, body.output, body.displayName);
+              json(response, 200, { displayName: displayName ?? null });
+            } catch (error) {
+              json(response, 422, { error: error instanceof Error ? error.message : String(error) });
+            }
+          })();
+          return;
+        }
         if (request.method === "POST" && url.pathname === "/__studio/mutation") {
           void (async () => {
             try {
@@ -577,8 +593,21 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
           return;
         }
         if (url.pathname === "/__studio/library") {
+          const section = url.searchParams.get("section");
+          if (section !== "tasks" && section !== "artifacts") {
+            json(response, 400, { error: "Choose tasks or artifacts with the section parameter" });
+            return;
+          }
+          const media = url.searchParams.get("media") ?? undefined;
+          if (media !== undefined && media !== "image" && media !== "video" && media !== "audio") {
+            json(response, 400, { error: "Choose image, video or audio with the media parameter" });
+            return;
+          }
           const before = url.searchParams.get("before") ?? undefined;
-          void readLibrary(before).then(
+          const run = url.searchParams.get("run") ?? undefined;
+          const build = url.searchParams.get("build") ?? undefined;
+          void readLibrary({ section, ...(media === undefined ? {} : { media }), ...(before === undefined ? {} : { before }),
+            ...(run === undefined ? {} : { run }), ...(build === undefined ? {} : { build }) }).then(
             (view) => json(response, 200, view),
             (error) => json(response, 500, { error: error instanceof Error ? error.message : String(error) }),
           );
@@ -662,13 +691,12 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
           void (async () => {
             const build = url.searchParams.get("build");
             const output = url.searchParams.get("output");
-            const valuePath = url.searchParams.get("path");
-            if (build === null || output === null || valuePath === null || options.buildLibrary === undefined) {
+            if (build === null || output === null || options.buildLibrary === undefined) {
               response.statusCode = 404;
               response.end();
               return;
             }
-            const artifact = await options.buildLibrary.openArtifact(build, output, valuePath);
+            const artifact = await options.buildLibrary.openArtifact(build, output);
             if (artifact === undefined) {
               response.statusCode = 404;
               response.end();

package/packages/studio/src/shared.ts

@@ -190,12 +190,14 @@ export type StudioTaskView = {
   readonly note?: string;
   readonly highlightedOutputs?: readonly string[];
   readonly createdAt: number;
-  readonly status: "queued" | "running" | "waiting" | "complete" | "failed" | "cancelled" | "active" | "blocked" | "unknown";
+  readonly finishedAt?: number;
+  readonly ongoing: boolean;
+  readonly status: "queued" | "running" | "waiting" | "complete" | "failed" | "cancelled" | "saving-result" | "attention";
+  readonly detail?: string;
+  readonly requests?: { readonly total: number; readonly completed: number };
   readonly source: string;
   readonly run?: string;
   readonly targets: readonly string[];
-  readonly acceptedRecords: number;
-  readonly outstandingCommands: number;
   readonly operations: readonly {
     readonly status: "pending" | "completed" | "failed" | "cancelled";
     readonly phase?: string;
@@ -206,7 +208,10 @@ export type StudioTaskView = {
 };
 
 export type StudioArtifactView = {
-  /** Build-qualified identity derived from the public Output and its value path. */
+  readonly nameEditable?: boolean;
+  /** Author-provided display name; the Output identifier remains unchanged. */
+  readonly displayName?: string;
+  /** File-owner identity; references to the same file share one card. */
   readonly id: string;
   readonly build: string;
   readonly createdAt: number;
@@ -214,18 +219,27 @@ export type StudioArtifactView = {
   readonly highlighted: boolean;
   readonly buildTitle?: string;
   readonly buildNote?: string;
-  readonly valuePath: string;
-  readonly ownerBuild: string;
+  readonly ownerBuild?: string;
   readonly ownerOutput: string;
   readonly filePath: string;
   readonly size: number;
   readonly mediaType: string;
   readonly source: string;
   readonly run?: string;
+  readonly origins: readonly { readonly build: string; readonly output: string; readonly run?: string; readonly source: string }[];
+};
+
+export type StudioLibraryRequest = {
+  readonly media?: "image" | "video" | "audio";
+  readonly section: "tasks" | "artifacts";
+  readonly before?: string;
+  readonly run?: string;
+  readonly build?: string;
 };
 
 /** Read-only view of the Runtime context selected for this Studio environment. */
 export type StudioLibraryView = {
+  readonly section: StudioLibraryRequest["section"];
   readonly environment: string;
   readonly runtime?: string;
   /** Cursor for the next older page of immutable Build Results. */

package/packages/studio/src/studio-registry.ts

@@ -14,6 +14,7 @@ import type {
   StudioSpan,
 } from "@hypit/studio-adapter";
 import { studioParameterControls } from "@hypit/studio-adapter";
+import { parameterOption } from "./parameter-values.js";
 import { compositionTypes } from "@hypit/composition";
 import { sameModule, sameType } from "@hypit/protocol";
 import type { ModuleRef, TypeRef } from "@hypit/protocol";
@@ -67,6 +68,27 @@ function validateInspector(
     if (field.control === "select" && (field.options === undefined || field.options.length === 0)) {
       throw new Error(`${subject} Inspector field ${field.binding} has no select options`);
     }
+    const choices = (field.options ?? []).map(parameterOption);
+    if (choices.some(option => !option.label.trim() || !["string", "number", "boolean"].includes(typeof option.value)
+      || typeof option.value === "number" && !Number.isFinite(option.value))
+      || new Set(choices.map(option => JSON.stringify(option.value))).size !== choices.length) {
+      throw new Error(`${subject} Inspector field ${field.binding} has invalid or repeated choices`);
+    }
+    const numeric = field.number;
+    if (numeric !== undefined) {
+      if (field.control !== "number" || numeric.scale !== undefined && (!Number.isFinite(numeric.scale) || numeric.scale <= 0)
+        || numeric.step !== undefined && (!Number.isFinite(numeric.step) || numeric.step <= 0)
+        || numeric.minimum !== undefined && !Number.isFinite(numeric.minimum)
+        || numeric.maximum !== undefined && !Number.isFinite(numeric.maximum)
+        || numeric.minimum !== undefined && numeric.maximum !== undefined && numeric.minimum > numeric.maximum
+        || numeric.suffixes !== undefined && (numeric.suffixes.length === 0 || numeric.suffixes.some(suffix => !suffix.trim()))) {
+        throw new Error(`${subject} Inspector field ${field.binding} has an invalid numeric presentation`);
+      }
+    }
+    if (field.multiline && field.control !== "text") throw new Error(`${subject} multiline editing requires text`);
+    if (field.swatches !== undefined && (field.control !== "color" || field.swatches.some(color => !/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(color)))) {
+      throw new Error(`${subject} color suggestions require hex colors`);
+    }
   }
 }