@hypit/hypit 0.1.3 → 0.1.5

package/packages/temporal/src/component.ts

@@ -2,8 +2,7 @@ import type { ComponentPackage, ProducerHandlerContext } from "@hypit/component-
 import { canonicalize } from "@hypit/protocol";
 import type { StoredValue } from "@hypit/protocol";
 import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
-import type { ProgramSpace } from "@hypit/program-space";
-import type { SemanticTrack } from "@hypit/semantic-track";
+import type { Timeline } from "@hypit/timeline";
 
 import {
   composeTemporalWindow,
@@ -31,14 +30,14 @@ export const temporalComponent = {
     { producer: temporalProducers.projectProgramInstant, handler: ({ inputs }) => ({ outputs: { instant: output(projectProgramInstant({
       itemId: instantSpec(inputs).id,
       subjectId: instantSpec(inputs).subjectId,
-      space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+      timeline: inline<Timeline>(inputs.timeline?.value, "Timeline"),
       projection: instantSpec(inputs).projection,
       authority: instantSpec(inputs).authority,
     })) }, needs: {} }) },
     { producer: temporalProducers.projectSelectionInstant, handler: ({ inputs }) => ({ outputs: { instant: output(projectSelectionInstant({
       itemId: instantSpec(inputs).id,
       subjectId: instantSpec(inputs).subjectId,
-      semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
+      timeline: inline<Timeline>(inputs.timeline?.value, "Timeline"),
       selection: inline<NarrativeSelectionRef>(inputs.selection?.value, "NarrativeSelection"),
       projection: instantSpec(inputs).projection,
       authority: instantSpec(inputs).authority,
@@ -46,7 +45,7 @@ export const temporalComponent = {
     { producer: temporalProducers.projectSegmentInstant, handler: ({ inputs }) => ({ outputs: { instant: output(projectSegmentInstant({
       itemId: instantSpec(inputs).id,
       subjectId: instantSpec(inputs).subjectId,
-      semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
+      timeline: inline<Timeline>(inputs.timeline?.value, "Timeline"),
       segment: inline<NarrativeExcerpt>(inputs.segment?.value, "NarrativeExcerpt"),
       projection: instantSpec(inputs).projection,
       authority: instantSpec(inputs).authority,
@@ -54,7 +53,7 @@ export const temporalComponent = {
     { producer: temporalProducers.projectMomentInstant, handler: ({ inputs }) => ({ outputs: { instant: output(projectMomentInstant({
       itemId: instantSpec(inputs).id,
       subjectId: instantSpec(inputs).subjectId,
-      semantic: inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
+      timeline: inline<Timeline>(inputs.timeline?.value, "Timeline"),
       moment: inline<NarrativeMomentRef>(inputs.moment?.value, "NarrativeMoment"),
       projection: instantSpec(inputs).projection,
       authority: instantSpec(inputs).authority,

package/packages/temporal/src/index.ts

@@ -1,6 +1,6 @@
 import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
 import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
-import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
 import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
 
 const string = { kind: "string", minLength: 1 } as const;
@@ -65,7 +65,7 @@ export const temporalManifest: ModuleManifest = {
   format: "hypit.module@1",
   name: temporalModuleRef.name,
   version: temporalModuleRef.version,
-  dependencies: [narrativeDependency, programSpaceDependency, semanticTrackDependency],
+  dependencies: [narrativeDependency, programSpaceDependency, timelineDependency],
   types: [
     { name: temporalTypes.instantSpec.name },
     { name: temporalTypes.instant.name },
@@ -75,16 +75,16 @@ export const temporalManifest: ModuleManifest = {
   capabilities: [],
   producers: [
     { name: temporalProducers.projectProgramInstant.name,
-      inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "spec", type: temporalTypes.instantSpec }],
+      inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "spec", type: temporalTypes.instantSpec }],
       outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },
     { name: temporalProducers.projectSelectionInstant.name,
-      inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "selection", type: narrativeTypes.selection }, { name: "spec", type: temporalTypes.instantSpec }],
+      inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "selection", type: narrativeTypes.selection }, { name: "spec", type: temporalTypes.instantSpec }],
       outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },
     { name: temporalProducers.projectSegmentInstant.name,
-      inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "segment", type: narrativeTypes.excerpt }, { name: "spec", type: temporalTypes.instantSpec }],
+      inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "segment", type: narrativeTypes.excerpt }, { name: "spec", type: temporalTypes.instantSpec }],
       outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },
     { name: temporalProducers.projectMomentInstant.name,
-      inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "moment", type: narrativeTypes.moment }, { name: "spec", type: temporalTypes.instantSpec }],
+      inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "moment", type: narrativeTypes.moment }, { name: "spec", type: temporalTypes.instantSpec }],
       outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },
     { name: temporalProducers.composeWindow.name,
       inputs: [{ name: "spec", type: temporalTypes.windowSpec }, { name: "start", type: temporalTypes.instant }, { name: "end", type: temporalTypes.instant }],
@@ -108,3 +108,5 @@ export const temporalWindowSchema: ValueSchema = object({
   end: { schema: temporalInstantSchema },
   span: { schema: frameSpanSchema },
 });
+
+export { durationInFrames } from "./rational.js";

package/packages/temporal/src/location.ts

@@ -2,11 +2,11 @@ import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from
 import { programSpaceFrameCount } from "@hypit/program-space";
 import {
   momentFrame,
-  projectSemanticProgramSpace,
+  projectTimelineSpace,
   segmentFrameSpan,
   selectionFrameSpan,
-} from "@hypit/semantic-track";
-import type { SemanticTrack } from "@hypit/semantic-track";
+} from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
 
 import type {
   LocatedMoment,
@@ -22,10 +22,10 @@ function assertLocatedFrame(frame: number, totalFrames: number, label: string):
 }
 
 export function locateSelection(
-  semantic: SemanticTrack,
+  semantic: Timeline,
   selection: NarrativeSelectionRef,
 ): LocatedSelection {
-  const space = projectSemanticProgramSpace(semantic);
+  const space = projectTimelineSpace(semantic);
   const totalFrames = programSpaceFrameCount(space);
   const span = selectionFrameSpan(semantic, selection);
   assertLocatedFrame(span.startFrame, totalFrames, `NarrativeSelection ${selection.id} start`);
@@ -34,26 +34,26 @@ export function locateSelection(
 }
 
 export function locateMoment(
-  semantic: SemanticTrack,
+  semantic: Timeline,
   moment: NarrativeMomentRef,
 ): LocatedMoment {
-  const space = projectSemanticProgramSpace(semantic);
+  const space = projectTimelineSpace(semantic);
   const totalFrames = programSpaceFrameCount(space);
   const frame = momentFrame(semantic, moment);
   assertLocatedFrame(frame, totalFrames, `NarrativeMoment ${moment.id} cue`);
   return { id: moment.id, cue: { frame } };
 }
 
-export function locateProgram(semantic: SemanticTrack): LocatedProgram {
-  const space = projectSemanticProgramSpace(semantic);
+export function locateProgram(semantic: Timeline): LocatedProgram {
+  const space = projectTimelineSpace(semantic);
   return { id: "program", start: { frame: 0 }, end: { frame: programSpaceFrameCount(space) } };
 }
 
 export function locateSegment(
-  semantic: SemanticTrack,
+  semantic: Timeline,
   segment: NarrativeExcerpt,
 ): LocatedSegment {
-  const space = projectSemanticProgramSpace(semantic);
+  const space = projectTimelineSpace(semantic);
   const totalFrames = programSpaceFrameCount(space);
   const span = segmentFrameSpan(semantic, segment);
   assertLocatedFrame(span.startFrame, totalFrames, `Narrative Segment ${segment.id} start`);

package/packages/temporal/src/projection.ts

@@ -1,8 +1,8 @@
 import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
 import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
 import type { ProgramSpace } from "@hypit/program-space";
-import { projectSemanticProgramSpace } from "@hypit/semantic-track";
-import type { SemanticTrack } from "@hypit/semantic-track";
+import { projectTimelineSpace } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
 
 import { locateMoment, locateProgram, locateSegment, locateSelection } from "./location.js";
 import { add, compare, durationInFrames, quantizeBoundary, rational } from "./rational.js";
@@ -169,17 +169,17 @@ function projectedInstant(
 export function projectSelectionInstant(input: {
   readonly itemId: string;
   readonly subjectId: string;
-  readonly semantic: SemanticTrack;
+  readonly timeline: Timeline;
   readonly selection: NarrativeSelectionRef;
   readonly projection: TemporalInstantExpression;
   readonly authority: TemporalInstantSpec["authority"];
 }): ProjectedInstant {
-  const space = projectSemanticProgramSpace(input.semantic);
-  const program = locateProgram(input.semantic);
-  const selection = locateSelection(input.semantic, input.selection);
+  const space = projectTimelineSpace(input.timeline);
+  const program = locateProgram(input.timeline);
+  const selection = locateSelection(input.timeline, input.selection);
   return projectedInstant(
     { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
-    { spaceId: space.id, narrativeId: input.semantic.narrativeId, kind: "selection", id: selection.id },
+    { spaceId: space.id, narrativeId: input.selection.narrativeId, kind: "selection", id: selection.id },
     projectTemporalInstant(input.projection, { program, selection }, space),
   );
 }
@@ -187,17 +187,17 @@ export function projectSelectionInstant(input: {
 export function projectMomentInstant(input: {
   readonly itemId: string;
   readonly subjectId: string;
-  readonly semantic: SemanticTrack;
+  readonly timeline: Timeline;
   readonly moment: NarrativeMomentRef;
   readonly projection: TemporalInstantExpression;
   readonly authority: TemporalInstantSpec["authority"];
 }): ProjectedInstant {
-  const space = projectSemanticProgramSpace(input.semantic);
-  const program = locateProgram(input.semantic);
-  const moment = locateMoment(input.semantic, input.moment);
+  const space = projectTimelineSpace(input.timeline);
+  const program = locateProgram(input.timeline);
+  const moment = locateMoment(input.timeline, input.moment);
   return projectedInstant(
     { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
-    { spaceId: space.id, narrativeId: input.semantic.narrativeId, kind: "moment", id: moment.id },
+    { spaceId: space.id, narrativeId: input.moment.narrativeId, kind: "moment", id: moment.id },
     projectTemporalInstant(input.projection, { program, moment }, space),
   );
 }
@@ -205,11 +205,11 @@ export function projectMomentInstant(input: {
 export function projectProgramInstant(input: {
   readonly itemId: string;
   readonly subjectId: string;
-  readonly space: ProgramSpace;
+  readonly timeline: Timeline;
   readonly projection: TemporalInstantExpression;
   readonly authority: TemporalInstantSpec["authority"];
 }): ProjectedInstant {
-  const space = input.space;
+  const space = projectTimelineSpace(input.timeline);
   const program = { id: "program" as const, start: { frame: 0 }, end: { frame: programSpaceFrameCount(space) } };
   return projectedInstant(
     { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
@@ -221,17 +221,17 @@ export function projectProgramInstant(input: {
 export function projectSegmentInstant(input: {
   readonly itemId: string;
   readonly subjectId: string;
-  readonly semantic: SemanticTrack;
+  readonly timeline: Timeline;
   readonly segment: NarrativeExcerpt;
   readonly projection: TemporalInstantExpression;
   readonly authority: TemporalInstantSpec["authority"];
 }): ProjectedInstant {
-  const space = projectSemanticProgramSpace(input.semantic);
-  const program = locateProgram(input.semantic);
-  const segment = locateSegment(input.semantic, input.segment);
+  const space = projectTimelineSpace(input.timeline);
+  const program = locateProgram(input.timeline);
+  const segment = locateSegment(input.timeline, input.segment);
   return projectedInstant(
     { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
-    { spaceId: space.id, narrativeId: input.semantic.narrativeId, kind: "segment", id: segment.id },
+    { spaceId: space.id, narrativeId: input.segment.narrativeId, kind: "segment", id: segment.id },
     projectTemporalInstant(input.projection, { program, segment }, space),
   );
 }

package/packages/temporal/src/rational.ts

@@ -1,4 +1,4 @@
-import type { ProgramSpace } from "@hypit/program-space";
+import type { ProgramClock } from "@hypit/program-space";
 
 import type { TemporalDuration } from "./types.js";
 
@@ -51,9 +51,9 @@ function safeInteger(value: number, label: string): bigint {
   return BigInt(value);
 }
 
-export function durationInFrames(duration: TemporalDuration, space: ProgramSpace): Rational {
-  const frameNumerator = safeInteger(space.frameRate.numerator, "ProgramSpace frame-rate numerator");
-  const frameDenominator = safeInteger(space.frameRate.denominator, "ProgramSpace frame-rate denominator");
+export function durationInFrames(duration: TemporalDuration, space: ProgramClock): Rational {
+  const frameNumerator = safeInteger(space.frameRate.numerator, "ProgramClock frame-rate numerator");
+  const frameDenominator = safeInteger(space.frameRate.denominator, "ProgramClock frame-rate denominator");
   switch (duration.unit) {
     case "frames":
       return rational(safeInteger(duration.value, "Frame duration"));

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. Timeline places each prepared Take independently; semantic
+stops use those placed anchor frames, including coincident anchors from overlapping Takes.
+
+## 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

@@ -2,24 +2,28 @@
 
 Shared SVML author-time projection helpers for `@hypit/temporal`. The Surface lowers authored
 Selection, Segment, Moment or explicit clock expressions to ordinary Instant projections and Window
-composition. A domain consumer receives the projected values and explicit ProgramSpace; it does not
+composition. A domain consumer receives the projected values and the shared Timeline; it does not
 locate Script words or infer a semantic source inside its renderer.
 
 The package exports `createTemporalWindowProjection`, `createTemporalInstantProjection`,
-`resolveTemporalContext`, `createTemporalSpace`, attribute vocabulary, and the exact duration/instant parsers. These are helpers for component
+`resolveTemporalContext`, 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
-with `resolveTemporalContext({ element, resolveReference })`, and pass the result to
-`createTemporalSpace({ id, element, ...context })`. Preserve its component and fragment drafts.
-Supply `...context, space: time.space` to each temporal projection helper, and pass `time.space.ref`
-to the domain Fragment. Its input Type is `programSpaceTypes.programSpace`.
+A Track Surface accepts `timeline={program.timeline}`. Resolve it with
+`resolveTemporalContext({ element, resolveReference })` and pass that context to each temporal
+projection helper. Wire `context.timeline.ref` directly into the component Fragment's Timeline port.
+Preserve the projections' returned records, components and fragments.
 
-A semantic context locates Script references and supplies the performance's time axis. A declared
-space supplies a clock for authored animation. Literal times and program boundaries work in either
-context. A Script reference needs `semantic` to locate it; the renderer never invents that mapping.
+The context contains one required `timeline` reference. Program time and Script references both
+project against it. Pure animation uses a zero-Take Timeline with an authored extent. Script events
+use the anchors provided by its placed Takes. Drawing Producers receive that same Timeline and the
+projected Instants/Windows; they need no Script parser or separate time-range input.
 
 ## Window forms
 
@@ -66,10 +70,26 @@ can deliberately admit only that form; consumers need not expose unrelated tempo
 
 The Surface supplies an author-facing `subjectId` for the actual item whose time is being projected,
 separately from graph-qualified operation ids. The graph wires the resulting Instant or Window and
-ProgramSpace into the consumer. Keep projection outside the domain Producer: it consumes resolved
+Timeline into the consumer. Keep projection outside the domain Producer: it consumes resolved
 time and implements its own schedule or state, while the shared temporal protocol retains where that
 time came from. An outer lifetime and child activations are separate inputs when a component persists
 between events.
 
 Script's `@`, `~@`, close markers and Moment syntax belong to `@hypit/script`; media playback belongs
 to `@hypit/media-track`; a graphic component's reveal or preset semantics belong to that component.
+
+## Independently bound endpoints
+
+For a Window whose endpoints refer to different semantic sources, use `start-source` and
+`end-source`. The expression still states the kind and boundary; each binding supplies that source:
+
+```svml
+<example:Item start-source={story.segment.next} start="segment.start"
+  end-source={story.segment.previous} end="segment.end"/>
+```
+
+This describes an overlapping physical interval without authoring a backwards Script Selection.
+The same endpoint bindings accept Selections or Moments with their corresponding expressions.
+`segment`, `selection` and `moment` remain convenient shared bindings when both expressions use the
+same source. Explicit expressions retain local parameter writeback; these bindings do not move the
+referenced Script anchors when the expression's offset is edited.

package/packages/temporal-markup/package.json

@@ -11,7 +11,7 @@
     "@hypit/elaborator": "workspace:*",
     "@hypit/markup": "workspace:*",
     "@hypit/narrative": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/timeline": "workspace:*",
     "@hypit/temporal": "workspace:*",
     "@hypit/program-space": "workspace:*"
   }