@hypit/hypit 0.1.3 → 0.1.4

package/packages/temporal-markup/EDITING.md

@@ -0,0 +1,183 @@
+# Author-directed time editing
+
+The shared temporal author forms declare what Studio can edit. The tables below describe their
+implemented behavior; a component's Companion also supplies the actual Source bindings.
+The runtime projection types remain `@1`.
+
+## Relationships, expressions, and resolved time
+
+Selection and Moment name relationships in a Narrative. A Selection names two anchors; a Moment
+names one. Neither carries a duration measured in seconds. Segment and Program boundaries retain
+their structural meaning alongside word boundaries.
+
+A temporal expression describes how to obtain time from those relationships or from a clock.
+Projection resolves that description in a ProgramSpace. Its products are TemporalInstant and
+TemporalWindow, which a component consumes to implement its own schedule and appearance.
+
+In temporal author attributes, `{story.moment.reveal}` is a direct typed reference. Quoted values
+such as `"2s"` and `"moment.cue + 2f"` are clock descriptions. Quotation marks do not themselves
+produce an Instant or Window, and braces elsewhere in SVML can reference any public value type.
+Both semantic references and clock descriptions reach consumers through temporal projection.
+The consumer's role determines whether one Instant or a Window is needed.
+
+The editing rule is: **edit the relationship or parameter the author exposed, preserving the
+relationship they chose to depend on.** Knowing where a result came from does not by itself grant
+an inverse that changes that source.
+
+## Direct bindings
+
+| Author form | Move | Leading edge | Trailing edge |
+| --- | --- | --- | --- |
+| `during={story.selection.proof}` | Move both Selection anchors by the same number of semantic stops; duration may change. | Change its start anchor. | Change its end anchor. |
+| `at={story.moment.reveal}` for an Instant | Change the Moment anchor. | Not applicable. | Not applicable. |
+| `at={story.selection.proof} boundary="start"` for an Instant | Change only the Selection start anchor. | Not applicable. | Not applicable. |
+| `at={story.selection.proof} boundary="end"` for an Instant | Change only the Selection end anchor. | Not applicable. | Not applicable. |
+| `during={story.segment.opening}` or `during="program"` | Follow the structural span; no timeline write. | No timeline write. | No timeline write. |
+| A directly selected Segment boundary | Follow that structural boundary; no timeline write. | Not applicable. | Not applicable. |
+
+A shared Selection or Moment is edited once in Script. All its consumers follow after compilation.
+An item's placement in a track does not make its own private copy of that relationship.
+
+Word starts, word ends, Segment starts, and Segment ends are equally eligible semantic anchors.
+Selection starts do not inherently prefer word starts; Selection ends do not inherently prefer
+word ends. Endpoints can include pauses by referring to the appropriate neighboring anchor.
+
+## An event and a duration
+
+These forms expose two independent decisions: an event or clock position, and a duration.
+
+| Author form | Move | Leading edge | Trailing edge |
+| --- | --- | --- | --- |
+| `at={story.moment.reveal} for="8f"` | Change the Moment; keep `for`. | No handle. | Change `for`; keep the Moment. |
+| `until={story.moment.reveal} for="8f"` | Change the Moment; keep `for`. | Change `for`; keep the Moment. | No handle. |
+| `at="2s" for="8f"` | Change `at`; keep `for`. | No handle. | Change `for`; keep `at`. |
+| `until="2s" for="8f"` | Change `until`; keep `for`. | Change `for`; keep `until`. | No handle. |
+
+Moving an event-and-duration window preserves duration. Moving a direct Selection window preserves
+semantic step displacement instead. These are different author decisions, so they have different
+behavior even when their current rectangles look identical.
+
+The unavailable edge does not secretly edit both the event and the duration. Duration editing is
+frame-based; semantic event editing selects an anchor. There is no `at` plus `until` Window form:
+current forms are `during`, `at/for`, `until/for`, and `start/end`.
+
+## Clock positions and explicit offsets
+
+A literal Instant such as `at="2s"` exposes one numeric time and can move by rewriting that value.
+A reference expression exposes a local offset while retaining its referenced event:
+
+```svml
+moment={story.moment.reveal}
+instant="moment.cue + 2f"
+```
+
+Moving this Instant changes the signed offset only. It does not relocate the Moment in Script.
+The same rule applies to an explicit offset from a selected boundary or a Program boundary.
+The expression's reference remains unchanged through the write.
+
+A bare reference expression such as `instant="moment.cue"` has an implicit zero offset. Moving it
+writes an offset such as `moment.cue+3f`; it leaves the Moment in Script unchanged. The direct
+binding `at={...}` is the form that edits the Moment itself.
+
+Bare references and explicit `+0f` have the same editing behavior. Writeback uses an explicit frame
+offset, including at zero. Positive, zero, and negative offsets belong to the same editing operation,
+subject to the resulting projection being usable.
+
+The existing syntax uses `instant` for expressions and a separate typed `moment`, `selection`, or
+`segment` attribute to bind their source. This design does not add an implicit name resolver or
+put arithmetic inside `{...}`. Unifying surface attribute spellings is a separate usability choice,
+not a prerequisite for establishing these edit semantics.
+
+## Independently authored endpoints
+
+`start="..." end="..."` expresses a deliberately assembled Window. Its expressions may use different
+sources, boundaries, absolute times, and offsets. This form remains available for production,
+including pure motion graphics and windows extending around a spoken passage.
+
+Each endpoint is edited exactly like an Instant expression: a literal changes its absolute time;
+a reference changes its local offset. A leading trim changes `start`, a trailing trim changes `end`,
+and a whole-window move shifts both endpoints by the same frame delta. Each expression retains its
+own reference, even when the endpoints depend on different sources. The referenced Script markers
+remain unchanged. Companion bindings identify the two writable source parameters.
+
+## Seconds and frames
+
+Seconds and milliseconds describe clock duration; frames describe steps at the ProgramSpace's
+frame rate. `2s` remains two seconds when the rate changes, whereas `60f` spans two seconds at 30fps
+and one second at 60fps. Parsing retains that authored unit. Projection uses exact rational arithmetic
+and rounds the resulting position to the nearest frame boundary, with half-frame ties rounding later.
+
+Timeline gestures operate on whole frames in the current ProgramSpace. A changed absolute value is
+written in frames, and a changed reference expression receives a frame offset. Unedited expressions
+retain their spelling and units. This makes a drag's result exact at the current frame rate without
+silently converting all authored clock durations into frame counts.
+
+## Semantic stops and coincident anchors
+
+Script order, anchor identity, and projected frame position are separate data:
+
+- Script order determines which inline Selection an author surface can express.
+- Projected frame position determines where an event appears in the current performance.
+- Anchor identity determines which relationship survives later changes to that performance.
+
+Build the gesture's semantic stops from distinct projected frame positions in chronological order.
+Several anchors at one frame occupy one stop but retain their individual identities. A direct
+Selection move advances both endpoints by the same signed number of stops. It does not shift a raw
+anchor-array index, assume one stop is one word, or preserve a duration measured in frames.
+
+Ties first retain the current anchor where it is still a candidate, then prefer its kind, then use
+a stable declared order. This is a default choice among coincident candidates, not a hierarchy of
+valid anchors. Selecting a semantic marker shows its exact anchors in the Inspector. Where declared
+handles allow it, a choice lists the other anchors at the same frame; horizontal mouse position alone
+cannot distinguish them. That explicit choice uses the same Script adjustment operation as dragging.
+
+Segment overlap or gaps can change temporal order without changing Script order. Stop construction
+must not assume contiguous Segments. The current SemanticTrack implementation still concatenates
+Take durations; introducing explicit Take placement is separate work.
+
+## Selection, projection, and consumption
+
+A Selection that is forward in Script may locate to equal or reversed frame endpoints. This does
+not alone establish whether every use of that Selection is invalid. A consumer may use only its
+start, or an expression may add offsets before composing a Window.
+
+Script validates the relationship it can express. Temporal projection validates the resulting
+Instant or Window in its ProgramSpace. Components validate their own use of those results.
+Studio offers only gestures with a declared inverse and candidate targets that preserve the
+edited object's usable projection. It does not add a global positive-duration rule to Selection.
+
+Both endpoints of a range adjustment are written in one operation. Recompilation remains the check
+for effects on other consumers of the shared relationship. An unsuccessful publication leaves the
+previous source and displayed state in place through the existing source transaction; this does not
+introduce a Build recovery workflow or a second mutable source of truth.
+
+A hidden or invalid initial object does not need an automatic repair interface. Conversely, a valid
+editable object must not disappear because the editor committed a target its own projection cannot
+represent. The relevant closure is over meaningful relationships and supported operations, not every
+possible raw spelling of the document.
+
+## Implementation ownership
+
+The existing protocol already distinguishes `TemporalSource` from `TemporalInstantAuthority`.
+Preserve this separation. A source says what time depends on; authority identifies an intentional
+write target. The `fixed` case means no temporal gesture writes that endpoint, not that all author
+parameter editing is forbidden.
+
+- `@hypit/script` owns tokenization, anchor identities, legal marker sites, and structural writeback.
+  It normalizes equivalent marker whitespace, retains punctuation and attributes, writes coincident
+  markers together, and preserves all unrelated relationships and caption information.
+- `@hypit/temporal-markup` owns the interpretation of each time form and declares its write targets.
+  Direct semantic references expose semantic targets; quoted time expressions expose parameter
+  targets, including implicit zero offsets and independent endpoints. Structural bindings retain
+  their structural boundaries without a timeline write target.
+- `@hypit/temporal` resolves time and validates its results. It does not infer a user editing choice
+  from invertibility or know Studio's UI.
+- Companion/Studio translates those declared relationships into the finite operations above.
+  Existing `after-start` and `before-end` duration relationships already distinguish event-and-duration
+  windows. Explicit source bindings remain the write allowlist. Component names and media types
+  do not decide which operation is available.
+
+Script tests exercise repeated marker moves and return trips across English, Chinese, Dual Text,
+punctuation, token attributes, and empty Segments. Temporal Markup tests check author authority;
+Studio tests check handles, semantic-stop movement, projected validity, and offset writes through zero.
+The same semantic gesture projection is used for the timeline preview and server-side validation.

package/packages/temporal-markup/README.md

@@ -9,6 +9,10 @@ The package exports `createTemporalWindowProjection`, `createTemporalInstantProj
 `resolveTemporalContext`, `createTemporalSpace`, attribute vocabulary, and the exact duration/instant parsers. These are helpers for component
 Surfaces, not standalone author tags or a new Track.
 
+The editing behavior is specified in [Author-directed time editing](EDITING.md).
+It separates direct bindings, durations, and explicit offsets from derived results, with a precise
+write target for each supported gesture.
+
 ## Time context
 
 A Track Surface can accept `semantic={speech.semantic}` or `space={animation}`. Resolve that choice

package/packages/typography-track-studio/package.json

@@ -4,11 +4,16 @@
   "license": "SEE LICENSE IN LICENSE",
   "private": true,
   "type": "module",
-  "exports": { ".": "./src/index.ts" },
-  "hypit": { "activation": "./src/activation.ts" },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
   "dependencies": {
     "@hypit/composition": "workspace:*",
     "@hypit/studio-adapter": "workspace:*",
-    "@hypit/typography-track": "workspace:*"
+    "@hypit/typography-track": "workspace:*",
+    "@hypit/fonts-open": "workspace:*"
   }
 }

package/packages/typography-track-studio/src/index.ts

@@ -1,9 +1,12 @@
+import { openFontStudioFields } from "@hypit/fonts-open/studio";
 import { typographyTrackMarkupSurfaces, typographyTrackModuleRef, typographyTrackTypes } from "@hypit/typography-track";
 import type { TypographyTrackProgram } from "@hypit/typography-track";
 import { compositionTypes } from "@hypit/composition";
 import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration } from "@hypit/studio-adapter";
 import { childEntities, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource, textLayer } from "@hypit/studio-adapter";
 
+const fontInspector = openFontStudioFields("style");
+
 const typographyProperties = (typographyTrackMarkupSurfaces
   .find((surface) => surface.name === "style")?.vocabulary.attributes
   .find((attribute) => attribute.name === "recipe")?.recipe ?? []);
@@ -105,11 +108,12 @@ export const typographyTrackStudioTrackCompanions: readonly StudioTrackCompanion
       { name: "content" },
       {
         name: "style",
+        referenced: [fontInspector.binding],
         recipe: { through: ["recipe"], bindings: typographyProperties.map(({ name }) => ({ name })) },
       },
       { name: "motion" },
     ],
-    inspector: typographyInspector,
+    inspector: [...fontInspector.fields, ...typographyInspector],
     requiredValues: ["program"], project: projectTypography,
     lane: { heightPx: 48 },
   },

package/packages/video-cli/README.md

@@ -37,14 +37,23 @@ Result or state. It names the Endpoint and its price page before it runs, and wr
 to the chosen file. `measure` estimates a passage locally:
 
 ```bash
-hypit transcribe reference.mp4 --to notes/reference.transcript.json [--language en|zh|es]
+hypit transcribe reference.mp4 --to notes/reference.transcript.json --language en
 hypit measure main.svml --segment hook --language en --pace normal --rounding round
 ```
 
+For `transcribe`, set `--language` to the spoken language: `en`, `zh` or `es`. Chinese speech uses `zh`, including
+Chinese speech containing English names; the requested language selects the recognition/alignment
+model, independently of the eventual caption font or script's simplified/traditional characters.
+
 `transcribe` uses the Profile's `whisperx-alignment` Endpoint (after
 extracting 16 kHz mono speech audio with ffmpeg). `measure` counts a Segment's pronunciation units at a
-delivery policy and prints the seconds to write as the literal `duration`; it opens no Profile and
-spends nothing. `--runtime <profile>` names the Profile; otherwise the project's `hypit runtime use`
+delivery policy and prints estimated seconds, the resolved rate, padding and rounding. Choose the
+literal `duration` from that estimate and the intended performance. `measure` opens no Profile and
+spends nothing. It accepts `--pace slow|normal|fast` or `--rate <units/s>`; JSON includes the resolved
+`rate` even when using a named pace. [Estimate](../estimate/README.md#units-and-delivery) explains
+Chinese/English units and choosing a whole-passage density.
+
+For `transcribe`, `--runtime <profile>` names the Profile; otherwise the project's `hypit runtime use`
 selection is read. Anything the Author Graph declares as an output is a Build, however quickly it
 comes back: pictures, clips and accepted voice references (`@hypit/mimo-speech`) carry the identity of the Source
 that produced them, so they are declared in the Source and go through `plan` and `build`. To hear a

package/packages/video-cli/src/creation.ts

@@ -9,6 +9,7 @@ import {
   countSpeechEstimateUnits,
   estimateSpeechDuration,
   resolveSpeechEstimateLanguage,
+  resolveSpeechEstimateRate,
   speechEstimatePolicyFromAttributes,
 } from "@hypit/estimate";
 import type { CanonicalValue, CapabilityRef, Need, StoredValue } from "@hypit/protocol";
@@ -275,8 +276,9 @@ async function transcribe(argv: readonly string[], io: CliIo, environment: Creat
   const parsed = parseArguments(argv, ["--language", "--to", "--runtime", "--workspace"]);
   assert(parsed.positionals.length === 1, "transcribe takes exactly one audio or video file");
   const source = resolve(environment.cwd, parsed.positionals[0]!);
-  const language = parsed.options.get("--language") ?? "en";
-  assert(language === "en" || language === "zh" || language === "es", "--language must be en, zh or es");
+  const language = parsed.options.get("--language");
+  assert(language === "en" || language === "zh" || language === "es",
+    "transcribe requires --language en|zh|es for the spoken language (use --language zh for Chinese)");
   const to = await destination(parsed, environment.cwd);
   const { profile, host } = await environment.openHost(
     parsed.options.get("--runtime"),
@@ -382,6 +384,7 @@ async function measure(argv: readonly string[], io: CliIo, environment: Creation
   }
   const pace = parsed.options.get("--pace");
   const rate = parsed.options.get("--rate");
+  assert(pace === undefined || rate === undefined, "measure takes either --pace or --rate, not both");
   const policy = speechEstimatePolicyFromAttributes({
     language: parsed.options.get("--language") ?? "auto",
     ...(rate === undefined ? { pace: pace ?? "normal" } : { rate }),
@@ -391,6 +394,7 @@ async function measure(argv: readonly string[], io: CliIo, environment: Creation
   const language = resolveSpeechEstimateLanguage(text, policy.language);
   const units = countSpeechEstimateUnits(text, language);
   const seconds = estimateSpeechDuration(sealText(text), policy);
+  const resolvedRate = resolveSpeechEstimateRate(policy, language);
   const view = {
     format: "hypit.video-cli-measure@1",
     ...where,
@@ -398,11 +402,13 @@ async function measure(argv: readonly string[], io: CliIo, environment: Creation
     units,
     language,
     policy,
+    rate: resolvedRate,
     seconds,
   };
   if (parsed.json) { io.write(`${JSON.stringify(view, null, 2)}\n`); return; }
-  const delivery = policy.rate === undefined ? `${policy.pace} pace` : `${policy.rate} units/s`;
-  io.write(`${seconds}s\n\n  ${units} pronunciation units · ${language} · ${delivery} · rounding ${policy.rounding}\n`
+  const delivery = `${resolvedRate} units/s${policy.pace === undefined ? "" : ` (${policy.pace})`}`;
+  io.write(`${Number(seconds.toFixed(3))}s\n\n  ${units} pronunciation units · ${language} · ${delivery}\n`
+    + `  padding ${policy.paddingSec ?? 0}s · rounding ${policy.rounding}\n`
     + `  ${"segment" in where ? `${where.segment} in ${where.source}` : `${text.length} characters`}\n`
     + "  Choose the request duration from this estimate, the intended performance, and the selected model's supported values.\n");
 }
@@ -416,7 +422,7 @@ export function writeCreationHelp(io: CliIo, topic?: CreationCommand): void {
       "hypit transcribe",
       "Establish word times with the whisperx-alignment Endpoint of the selected Runtime Profile.",
       "",
-      "  hypit transcribe <audio|video> --to <transcript.json> [--language en|zh|es] [--runtime <profile>] [--workspace <project>]",
+      "  hypit transcribe <audio|video> --to <transcript.json> --language en|zh|es [--runtime <profile>] [--workspace <project>]",
       "",
       "Extracts 16 kHz mono speech audio with ffmpeg and writes every word with its start and end in",
       "seconds. One immediate request; no Build, Result or state.",

package/packages/whisperx/README.md

@@ -17,6 +17,13 @@ projects the Take's audio to canonical 16 kHz mono `SpeechEvidenceAudio`; Whispe
 bytes. A deterministic local alignment then combines the returned evidence with the Segment and
 emits one self-contained `SemanticTake`.
 
+For Chinese speech, select `zh` (also `hypit transcribe --language zh` for a reference). WhisperX's
+Chinese alignment emits character-sized words, including letters inside some Latin names. The
+evidence adapter preserves those windows; the local alignment maps them onto Script's units, so
+a complete Latin name can consume several evidence words while neighboring Han characters retain
+their own times. Caption gets its displayed wording and Cue breaks from Script, independently of
+the recognizer's punctuation or simplified/traditional spelling.
+
 When the authored Segment has no Tokens, write the same Surface without `language`. Its start and
 end Anchors map directly to the prepared media's first and final frame. There are no words to align,
 so this branch requests no evidence audio and no WhisperX capability:

package/packages/workspace/src/index.ts

@@ -9,6 +9,8 @@ import type { BlobRef } from "@hypit/protocol";
 /** Repeatably openable transfer bytes admitted by the selected Workspace. */
 export type ArtifactAttachment = {
   readonly artifact: BlobRef;
+  /** Stable external address, when the Workspace supplies a file by reference. */
+  readonly location?: string;
   open(): Awaitable<AsyncIterable<Uint8Array>>;
 };
 

package/packages/workspace-fs-node/README.md

@@ -4,7 +4,10 @@ Reference Node filesystem implementation of the host-neutral `Workspace` contrac
 
 Every `open()` call creates one isolated compilation session. It canonicalizes real paths, confines
 local SourceUnit and Source Asset reads to the configured root, rejects symlink escapes, locks each
-edge to the first bytes observed and returns defensive Resource attachments.
+Source edge to the first bytes observed and returns defensive Resource attachments. File attachments
+also carry their resolved `file:` URI so Result publication can preserve the external reference.
+The Resource's identity and metadata belong to the compilation session; its file remains a live
+dependency rather than becoming a persistent snapshot.
 
 A Host may supply an external Source resolver. One explicit non-relative Source locator can then
 open a SourceUnit in a separate canonical root; that Source's relative imports and assets remain

package/packages/workspace-fs-node/src/workspace.ts

@@ -1,3 +1,4 @@
+import { pathToFileURL } from "node:url";
 import { randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { readFile, realpath, stat } from "node:fs/promises";
@@ -177,6 +178,7 @@ class NodeFilesystemWorkspaceSession implements WorkspaceSession {
     if (!this.#attachments.has(attachmentKey)) {
       this.#attachments.set(attachmentKey, {
         artifact: { ...artifact },
+        location: pathToFileURL(canonical).href,
         open: () => createReadStream(canonical),
       });
     }
@@ -189,7 +191,7 @@ class NodeFilesystemWorkspaceSession implements WorkspaceSession {
         const byResource = left.artifact.resource.localeCompare(right.artifact.resource);
         return byResource === 0 ? left.artifact.mediaType.localeCompare(right.artifact.mediaType) : byResource;
       })
-      .map((item) => ({ artifact: { ...item.artifact }, open: item.open }));
+      .map((item) => ({ ...item, artifact: { ...item.artifact } }));
   }
 }