@lokascript/framework 2.3.1 → 2.5.0

package/src/ir/explicit-renderer.ts

@@ -1,198 +1,5 @@
 /**
- * Explicit Syntax Renderer
- *
- * Serializes SemanticNode to the universal [command role:value ...] bracket syntax.
- * Zero dependencies beyond core types — no language-specific logic.
- *
- * Also renders annotations (@name(value)) and multi-line documents.
+ * Explicit Syntax Renderer — re-exported from @lokascript/intent
  */
 
-import type {
-  SemanticNode,
-  SemanticValue,
-  CommandSemanticNode,
-  CompoundSemanticNode,
-  EventHandlerSemanticNode,
-  ConditionalSemanticNode,
-  LoopSemanticNode,
-  LSEEnvelope,
-} from '../core/types';
-
-/**
- * Render a semantic node as explicit bracket syntax.
- *
- * Handles annotations (v1.2) — if the node has annotations, they are
- * prepended as @name or @name(value) before the bracket output.
- *
- * @example
- * ```typescript
- * renderExplicit(node) // "[toggle patient:.active destination:#button]"
- * // With annotations:
- * renderExplicit(annotatedNode) // "@timeout(5s) [fetch source:\"/api/users\"]"
- * ```
- */
-export function renderExplicit(node: SemanticNode): string {
-  let result: string;
-
-  // Handle compound nodes
-  if (node.kind === 'compound') {
-    const compoundNode = node as CompoundSemanticNode;
-    const renderedStatements = compoundNode.statements.map(stmt => renderExplicit(stmt));
-    result = renderedStatements.join(` ${compoundNode.chainType} `);
-  } else {
-    result = renderBracketCommand(node);
-  }
-
-  // Prepend annotations if present
-  if (node.annotations && node.annotations.length > 0) {
-    const annParts = node.annotations.map(ann =>
-      ann.value !== undefined ? `@${ann.name}(${ann.value})` : `@${ann.name}`
-    );
-    return annParts.join(' ') + ' ' + result;
-  }
-
-  return result;
-}
-
-/**
- * Render an LSEEnvelope as a multi-line document string.
- *
- * @example
- * ```typescript
- * renderDocument(envelope)
- * // "#!lse 1.2\n[toggle patient:.active]\n[add patient:.highlight]"
- * ```
- */
-export function renderDocument(envelope: LSEEnvelope): string {
-  const lines: string[] = [];
-
-  // Emit version header if not the default
-  if (envelope.lseVersion && envelope.lseVersion !== '1.0') {
-    lines.push(`#!lse ${envelope.lseVersion}`);
-  }
-
-  // Emit each node on its own line
-  for (const node of envelope.nodes) {
-    lines.push(renderExplicit(node));
-  }
-
-  return lines.join('\n');
-}
-
-// =============================================================================
-// Internal Helpers
-// =============================================================================
-
-/**
- * Render a single bracket command (non-compound node).
- */
-function renderBracketCommand(node: SemanticNode): string {
-  const parts: string[] = [node.action];
-
-  // Add roles
-  for (const [role, value] of node.roles) {
-    if (value.type === 'flag') {
-      parts.push(value.enabled ? `+${value.name}` : `~${value.name}`);
-    } else {
-      parts.push(`${role}:${valueToString(value)}`);
-    }
-  }
-
-  // Handle event handler body
-  if (node.kind === 'event-handler') {
-    const eventNode = node as EventHandlerSemanticNode;
-    if (eventNode.body && eventNode.body.length > 0) {
-      const bodyParts = eventNode.body.map(n => renderExplicit(n));
-      parts.push(`body:${bodyParts.join(' ')}`);
-    }
-  }
-
-  // Handle conditional branches (v1.1)
-  if (node.kind === 'conditional') {
-    const condNode = node as ConditionalSemanticNode;
-    if (condNode.thenBranch && condNode.thenBranch.length > 0) {
-      const thenParts = condNode.thenBranch.map(n => renderExplicit(n));
-      parts.push(`then:${thenParts.join(' ')}`);
-    }
-    if (condNode.elseBranch && condNode.elseBranch.length > 0) {
-      const elseParts = condNode.elseBranch.map(n => renderExplicit(n));
-      parts.push(`else:${elseParts.join(' ')}`);
-    }
-  }
-
-  // Handle loop body and metadata (v1.1)
-  if (node.kind === 'loop') {
-    const loopNode = node as LoopSemanticNode;
-    if (loopNode.loopVariant) {
-      parts.push(`loop-variant:${loopNode.loopVariant}`);
-    }
-    if (loopNode.loopVariable) {
-      parts.push(`variable:${loopNode.loopVariable}`);
-    }
-    if (loopNode.indexVariable) {
-      parts.push(`index-variable:${loopNode.indexVariable}`);
-    }
-    if (loopNode.body && loopNode.body.length > 0) {
-      const bodyParts = loopNode.body.map(n => renderExplicit(n));
-      parts.push(`loop-body:${bodyParts.join(' ')}`);
-    }
-  }
-
-  // Handle v1.2 command fields (try/catch/finally, async, match)
-  if (node.kind === 'command') {
-    const cmd = node as CommandSemanticNode;
-    if (cmd.body && cmd.body.length > 0) {
-      const bodyParts = cmd.body.map(n => renderExplicit(n));
-      parts.push(`body:${bodyParts.join(' ')}`);
-    }
-    if (cmd.catchBranch && cmd.catchBranch.length > 0) {
-      const catchParts = cmd.catchBranch.map(n => renderExplicit(n));
-      parts.push(`catch:${catchParts.join(' ')}`);
-    }
-    if (cmd.finallyBranch && cmd.finallyBranch.length > 0) {
-      const finallyParts = cmd.finallyBranch.map(n => renderExplicit(n));
-      parts.push(`finally:${finallyParts.join(' ')}`);
-    }
-    if (cmd.asyncVariant) {
-      parts.push(`async-variant:${cmd.asyncVariant}`);
-    }
-    if (cmd.asyncBody && cmd.asyncBody.length > 0) {
-      const asyncParts = cmd.asyncBody.map(n => renderExplicit(n));
-      parts.push(`async-body:${asyncParts.join(' ')}`);
-    }
-  }
-
-  return `[${parts.join(' ')}]`;
-}
-
-/**
- * Convert a semantic value to its explicit syntax string form.
- */
-function valueToString(value: SemanticValue): string {
-  switch (value.type) {
-    case 'literal':
-      if (typeof value.value === 'string') {
-        // Quote strings that contain spaces or are explicitly typed as strings
-        if (value.dataType === 'string' || /\s/.test(value.value)) {
-          return `"${value.value}"`;
-        }
-        return value.value;
-      }
-      return String(value.value);
-
-    case 'selector':
-      return value.value;
-
-    case 'reference':
-      return value.value;
-
-    case 'property-path':
-      return `${valueToString(value.object)}'s ${value.property}`;
-
-    case 'expression':
-      return value.raw;
-
-    case 'flag':
-      return value.name;
-  }
-}
+export { renderExplicit, renderDocument } from '@lokascript/intent';

package/src/ir/from-interchange.test.ts

@@ -427,6 +427,89 @@ describe('fromInterchangeNode: command conversion', () => {
     });
   });
 
+  it('infers destination role for scroll, skipping `to` marker', () => {
+    const node = fromInterchangeNode({
+      type: 'command',
+      name: 'scroll',
+      args: [
+        { type: 'identifier', value: 'to', name: 'to' },
+        { type: 'selector', value: '#target' },
+      ],
+    });
+
+    expect(node.action).toBe('scroll');
+    expect(node.roles.get('destination')).toEqual({
+      type: 'selector',
+      value: '#target',
+      selectorKind: 'id',
+    });
+    expect(node.roles.has('patient')).toBe(false);
+  });
+
+  it('infers destination for scroll across position/behavior markers', () => {
+    const node = fromInterchangeNode({
+      type: 'command',
+      name: 'scroll',
+      args: [
+        { type: 'identifier', value: 'to', name: 'to' },
+        { type: 'identifier', value: 'bottom', name: 'bottom' },
+        { type: 'identifier', value: 'of', name: 'of' },
+        { type: 'selector', value: '#chat' },
+        { type: 'identifier', value: 'smoothly', name: 'smoothly' },
+      ],
+    });
+
+    expect(node.roles.get('destination')).toEqual({
+      type: 'selector',
+      value: '#chat',
+      selectorKind: 'id',
+    });
+  });
+
+  it('infers patient role for push, skipping `url` marker', () => {
+    const node = fromInterchangeNode({
+      type: 'command',
+      name: 'push',
+      args: [
+        { type: 'identifier', value: 'url', name: 'url' },
+        { type: 'literal', value: '/page/2' },
+      ],
+    });
+
+    expect(node.action).toBe('push');
+    expect(node.roles.get('patient')).toEqual({ type: 'literal', value: '/page/2' });
+  });
+
+  it('infers patient role for replace, skipping `url` marker', () => {
+    const node = fromInterchangeNode({
+      type: 'command',
+      name: 'replace',
+      args: [
+        { type: 'identifier', value: 'url', name: 'url' },
+        { type: 'literal', value: '/new' },
+      ],
+    });
+
+    expect(node.action).toBe('replace');
+    expect(node.roles.get('patient')).toEqual({ type: 'literal', value: '/new' });
+  });
+
+  it('infers patient role for process, skipping `partials in` markers', () => {
+    const node = fromInterchangeNode({
+      type: 'command',
+      name: 'process',
+      args: [
+        { type: 'identifier', value: 'partials', name: 'partials' },
+        { type: 'identifier', value: 'in', name: 'in' },
+        { type: 'identifier', value: 'it' },
+      ],
+    });
+
+    expect(node.action).toBe('process');
+    // `it` is in DEFAULT_REFERENCES → wrapped as a reference value
+    expect(node.roles.get('patient')).toEqual({ type: 'reference', value: 'it' });
+  });
+
   it('wraps bare expression nodes as get command', () => {
     const node = fromInterchangeNode({
       type: 'binary',
@@ -759,17 +842,21 @@ describe('round-trip: InterchangeNode → SemanticNode → protocol JSON', () =>
     });
   });
 
-  it('event handler produces valid protocol JSON', () => {
+  it('event handler produces valid protocol JSON (compact trigger form)', () => {
     const node = fromInterchangeNode({
       type: 'event',
       event: 'click',
       body: [{ type: 'command', name: 'log', args: [{ type: 'literal', value: 'clicked' }] }],
     });
 
+    // Single-command bodies are emitted in the compact form — the body
+    // command's action is hoisted to the top level and the event name moves
+    // under `trigger.event`. See protocol.ts:canEmitCompactTrigger.
     const proto = toProtocolJSON(node);
-    expect(proto.kind).toBe('event-handler');
-    expect(proto.body).toHaveLength(1);
-    expect(proto.body![0].action).toBe('log');
+    expect(proto.kind).toBeUndefined();
+    expect(proto.action).toBe('log');
+    expect(proto.trigger).toEqual({ event: 'click' });
+    expect(proto.body).toBeUndefined();
   });
 
   it('if/else produces valid protocol JSON', () => {

package/src/ir/from-interchange.ts

@@ -428,6 +428,43 @@ export function renderExpr(node: INode): string {
 // Role Inference
 // =============================================================================
 
+/**
+ * Marker-keyword sets — mirror the runtime command parsers' skip lists so the
+ * inferred roles point at the real value, not the literal marker word.
+ */
+const SCROLL_MARKERS: ReadonlySet<string> = new Set([
+  'to',
+  'of',
+  'the',
+  'top',
+  'bottom',
+  'middle',
+  'center',
+  'nearest',
+  'left',
+  'right',
+  'smoothly',
+  'instantly',
+]);
+const URL_MARKERS: ReadonlySet<string> = new Set(['url']);
+const PARTIALS_IN_MARKERS: ReadonlySet<string> = new Set(['partials', 'in']);
+
+/**
+ * Return the first arg that isn't a marker identifier from the given set.
+ * Identifier args carry the marker word in `name` (or `value` as a fallback).
+ */
+function firstNonMarkerArg(args: INode[], markers: ReadonlySet<string>): INode | undefined {
+  for (const a of args) {
+    if (a.type === 'identifier') {
+      const ident = a as { name?: unknown; value?: unknown };
+      const word = typeof ident.name === 'string' ? ident.name : ident.value;
+      if (typeof word === 'string' && markers.has(word)) continue;
+    }
+    return a;
+  }
+  return undefined;
+}
+
 /**
  * Infer semantic roles from command name, positional args, modifiers, and target.
  * Mirrors the heuristics in core's from-core.ts inferRoles() function.
@@ -526,6 +563,28 @@ function inferRoles(
       break;
     }
 
+    // scroll [to] [position] target [smoothly|instantly]  →  destination=target
+    case 'scroll': {
+      const t = firstNonMarkerArg(args, SCROLL_MARKERS);
+      if (t) roles.destination = convertValue(t);
+      break;
+    }
+
+    // push|replace url <X>  →  patient=X
+    case 'push':
+    case 'replace': {
+      const t = firstNonMarkerArg(args, URL_MARKERS);
+      if (t) roles.patient = convertValue(t);
+      break;
+    }
+
+    // process partials in <X>  →  patient=X
+    case 'process': {
+      const t = firstNonMarkerArg(args, PARTIALS_IN_MARKERS);
+      if (t) roles.patient = convertValue(t);
+      break;
+    }
+
     default: {
       // Generic fallback: first arg as patient, target as destination
       if (args[0]) roles.patient = convertValue(args[0]);

package/src/ir/protocol-json.test.ts

@@ -136,20 +136,25 @@ describe('toProtocolJSON', () => {
   });
 
   describe('event-handler node', () => {
-    it('serializes body array recursively', () => {
+    it('serializes single-command body in compact form (trigger sugar)', () => {
+      // Single-command bodies round-trip through the compact form —
+      // `{action, roles, trigger: {event}}` — which is also what the runtime
+      // dispatch path reliably executes. See protocol.ts:canEmitCompactTrigger.
       const body = createCommandNode('toggle', { patient: createSelector('.active') });
       const node = createEventHandlerNode('on', { event: createLiteral('click', 'string') }, [
         body,
       ]);
       const json = toProtocolJSON(node);
-      expect(json.kind).toBe('event-handler');
-      expect(json.action).toBe('on');
-      expect(json.body).toHaveLength(1);
-      expect(json.body![0].kind).toBe('command');
-      expect(json.body![0].action).toBe('toggle');
+      expect(json.kind).toBeUndefined(); // defaults to 'command'
+      expect(json.action).toBe('toggle'); // body action is hoisted
+      expect(json.trigger).toEqual({ event: 'click' });
+      expect(json.roles).toMatchObject({ patient: { type: 'selector', value: '.active' } });
+      expect(json.body).toBeUndefined();
     });
 
-    it('serializes nested event-handler body', () => {
+    it('falls back to verbose form for multi-command event-handler body', () => {
+      // Compact form can only represent a single body command; multi-command
+      // bodies still use the verbose `kind: event-handler` form.
       const inner = createCommandNode('add', { patient: createSelector('.highlight') });
       const outer = createCommandNode('remove', { patient: createSelector('.active') });
       const node = createEventHandlerNode('on', { event: createLiteral('click', 'string') }, [
@@ -157,8 +162,12 @@ describe('toProtocolJSON', () => {
         outer,
       ]);
       const json = toProtocolJSON(node);
+      expect(json.kind).toBe('event-handler');
+      expect(json.action).toBe('on');
       expect(json.body).toHaveLength(2);
+      expect(json.body![0].action).toBe('add');
       expect(json.body![1].action).toBe('remove');
+      expect(json.trigger).toBeUndefined();
     });
   });