Skip to content

refactor(web_core): decouple GenericBinder and separate catalog-agnostic package entrypoints - #2353

Open
gspencergoog wants to merge 41 commits into
a2ui-project:v1_0_polishing_tsfrom
gspencergoog:v1_0_catalog_agnostic_refactor_ts
Open

refactor(web_core): decouple GenericBinder and separate catalog-agnostic package entrypoints#2353
gspencergoog wants to merge 41 commits into
a2ui-project:v1_0_polishing_tsfrom
gspencergoog:v1_0_catalog_agnostic_refactor_ts

Conversation

@gspencergoog

Copy link
Copy Markdown
Collaborator

Summary

This PR completes the catalog agnosticism refactor by addressing the remaining architectural decoupling recommendations:

  1. GenericBinder Decoupling & ValidationResult Support:

    • Replaced hardcoded property name checks (checks) in GenericBinder.getFieldBehavior with schema introspection via isCheckableField.
    • Updated GenericBinder check evaluation to natively support v1.0 ValidationResult objects ({ valid: boolean, message?: string }) in addition to boolean condition expressions.
    • Added unit tests in generic-binder.test.ts verifying dynamic validation messages and custom check property schemas.
  2. Catalog-Agnostic Package Entrypoints:

    • Created root src/index.ts exporting only catalog-agnostic core modules (catalog, state, processing, rendering, validating, reactivity, expressions, errors, events).
    • Created dedicated module barrels (src/catalog/index.ts, src/state/index.ts, src/rendering/index.ts, src/expressions/index.ts, src/reactivity/index.ts).
    • Updated package.json main, types, and exports["."], plus subpath exports (./catalog, ./state, ./processing, ./rendering, ./validating, ./reactivity, ./expressions, ./adapters).
    • Decoupled src/v0_9/index.ts by removing transitive basic_catalog re-exports.
    • Updated renderer imports in renderers/markdown/markdown-it and renderers/lit that specifically required v0.8 styles/types to explicitly import from @a2ui/web_core/v0_8.

Testing

  • All 364 web_core unit and integration tests pass.
  • All renderer unit and integration tests (Angular, Lit, Markdown-It) pass.

Add dedicated basic catalog component packages for protocol versions v0.8 and v1.0 in TypeScript web_core, reusing compatible v0.9 component definitions. Update conformance_test.mjs to use versioned basic catalog implementations instead of defaulting to v0.9 for all versions.
… catalog

Define dedicated Zod component schemas for v1.0 basic catalog (VideoApi with posterUrl, TextFieldApi with placeholder, SliderApi with steps) according to specification/v1_0/catalogs/basic/catalog.json.
… property aliases

Add comprehensive v0.8 specification property definitions and aliases (distribution/alignment for Row/Column/List, minValue/maxValue for Slider, textFieldType/text for TextField, entryPointChild/contentChild for Modal, tabItems for Tabs, MultipleChoice) to src/v0_8/basic_catalog/components/basic_components.ts.
…int in FunctionDefinitionSchema

Enforce in FunctionDefinitionSchema and catalog_definition.json that functions with requiresUserActivation=true must have allowedCallers='rendererOnly'. Added dedicated unit tests in src/v1_0/schema/verify-schema.test.ts.
…rs, string coercion, and redundant traversal optimization
…rray path indices, function recursion depth, and stream accumulation
…nces, validateComponentIntegrity, and analyzeTopology
…, context optional chaining, and index regex parsing
…ndler

- Add validation for call and call.call in callAgentFunction
- Add defensive options and catalogs fallback initialization in RpcHandler constructor
- Add non-null message check in handleCallRendererFunction and handleAgentFunctionResponse
- Add unit tests for null/undefined message and call validation edge cases

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request restructures the @a2ui/web_core package to export multiple subpaths, introduces v1.0 features including bidirectional RPC handling via RpcHandler, system functions like @index, and validation functions. It also adds robust validators for component integrity, path syntax, and graph topology, and updates SurfaceModel and GenericBinder to support these new structures. A review comment points out a performance optimization in MessageProcessor.getRendererCapabilities to avoid redundant calls to generateInlineCatalog when generating inline catalogs.

I am having trouble creating individual review comments. Click here to see my feedback.

typescript/web_core/src/processing/message-processor.ts (177-193)

medium

When options?.includeInlineCatalogs is enabled, generateInlineCatalog is called twice for each catalog: once to populate versionCaps.inlineCatalogs and once to populate the root-level inlineCatalogs property in the returned object. Since generateInlineCatalog performs relatively expensive Zod-to-JSON-schema conversions, we should generate the inline catalogs once and reuse the array to improve performance.

    let inlineCatalogs: Record<string, unknown>[] | undefined;
    if (options?.includeInlineCatalogs) {
      inlineCatalogs = this.catalogs.map(c =>
        this.generateInlineCatalog(c, options?.componentEnvelopeRef),
      );
      versionCaps.inlineCatalogs = inlineCatalogs;
    }

    return {
      supportedCatalogIds: this.catalogs.map(c => c.id),
      ...(inlineCatalogs
        ? {
            inlineCatalogs,
          }
        : {}),
      [version]: versionCaps,
    };

@gspencergoog
gspencergoog force-pushed the v1_0_polishing_ts branch 6 times, most recently from 68d805b to f26cfcb Compare August 20, 2026 21:09
@nan-yu
nan-yu force-pushed the v1_0_polishing_ts branch from f26cfcb to 8239223 Compare August 21, 2026 22:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant